Search Platform ledger line

POST

/v1/object-types/hospitality.platform_ledger_line/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.platform_ledger_line/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","cursor":"example","filters":[{"property":"id","type":"eq","value":"example"}],"limit":1,"order":"asc","property_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","scope":{"level":"tenant"},"sort_by":"created_at"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.platform_ledger_line/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "id", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

Search for instances. Filters eq, contains, gte and lte AND-compose; or / not are additive follow-ups. Pages with an opaque cursor; the +1 fetch returns has_more without a second round-trip. Ordered by sort_by (default created_at) in order (default ascending), id breaking ties; rows with no value for a property key sort last.

One balance transaction on the platform’s own processor balance (Stripe’s txn_…) that belongs to a hotel’s merchant account: the platform charge a destination payment was made with (and Stripe’s processing fee on it), the transfer that carried the hotel’s share, the application fee the platform earned, a refund and the reversal that recovered it, a chargeback’s withdrawal and what was passed back. Filed at the house the account is for, matched when it resolves to a ledger payment or case. Append-only; a line read again may gain a match it could not make before. The platform’s lines no hotel owns (its own payouts, Stripe’s fees on the platform and the tax on them, a reserve, a charge for an account no merchant account holds) are filed at the tenant scope of the operator’s own tenant, with no merchant account, never matched, their day the processor’s UTC day.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.platform_ledger_line:read

Request Body^required

application/json

object

branch

Optional open-branch id. Search composes that branch’s copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.

string format: uuid

cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string

filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array

One of:

object

property

required

Allowed value: id

type

required

Allowed value: eq

value

required

string

limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer

>= 1 <= 500

order

Direction of sort_by: asc (oldest / smallest first) or desc. A cursor is bound to the sort_by and order it was minted under; another pair is refused (422).

string

default: asc

Allowed values: asc desc

property_id

The house a desk stands in: keeps this property’s rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house’s — the meaning property_id has on the event tail.

string format: uuid

scope

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

sort_by

What the page is ordered by: the row’s created_at or updated_at, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).

string

default: created_at

Allowed values: created_at updated_at id psp_reference merchant_account_id property_id reporting_category line_type source_reference available_on occurred_at occurred_on payment_id dispute_id dispute_leg processor_account_reference

Responses

200

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

application/json

object

data

required

Array<object>

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.platform_ledger_line

properties

required

object

amount

required

Platform ledger line amount

Gross on the platform’s balance, as the processor states it (negative for money out — a transfer to the hotel, a chargeback)

object

amount

required

string format: decimal

currency

required

string format: iso-4217

available_on

The day the line's money became available on the platform's balance

string format: date

dispute_id

The chargeback the line moved money for (its object id) — the platform_ledger_line_for_dispute edge's target

string

dispute_leg

What the line did for its chargeback: the network's withdrawal or reinstatement, the amount or fee recovered from the hotel, money returned to the hotel after a late win

string

Allowed values: withdrawal reinstatement amount_recovered fee_recovered returned_to_hotel

fee

Platform ledger line fee

The processor’s fee on the line, charged to the platform

object

amount

required

string format: decimal

currency

required

string format: iso-4217

required

Platform ledger line id

string

line_type

The processor's own transaction type (`charge`, `transfer`, `application_fee`, `transfer_refund`, `adjustment`, …)

string

matched

required

Whether the line resolved to a ledger payment or chargeback

boolean

merchant_account_id

The hotel's merchant account the line was for (its object id) — the platform_ledger_line_for_merchant_account edge's target; absent on the platform's own line, which no hotel owns

string

net

Platform ledger line net

Gross less fee — what the line did to the platform’s balance

object

amount

required

string format: decimal

currency

required

string format: iso-4217

occurred_at

required

When the processor created the balance transaction

string format: date-time

occurred_on

required

The house's calendar day the line counts in — the processor's creation instant in the house's own timezone, the close's rule for a card payment's day; computed when the line is recorded

string format: date

payment_id

The ledger payment the line came from (its object id) — the platform_ledger_line_for_payment edge's target

string

processor_account_reference

On the platform's own line: the connected account (`acct_…`) the processor named for it when no merchant account on the ledger holds that account — what the operator looks up to place it

string

property_id

The house the account is for (its object id); absent on the platform's own line

string

psp_reference

required

The processor's id for the balance transaction on the platform's balance (Stripe `txn_…`) — the replay key

string

reporting_category

required

The processor's reporting category for the line, verbatim (`platform_earning` is an application fee; `other` when the processor named one this ledger does not know)

string

Allowed values: charge refund partial_capture_reversal dispute dispute_reversal transfer transfer_reversal platform_earning platform_earning_refund fee connect_reserved_funds connect_collection_transfer payout payout_reversal other_adjustment other tax risk_reserved_funds refund_failure topup topup_reversal

source_reference

The processor object the money moved for (`ch_…`, `tr_…`, `trr_…`, `fee_…`, `fr_…`, `re_…`, `du_…`, `py_…`)

string

provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object

pins

object

key

additional properties

object

pinned_at

string format: date-time

pinned_by

object

reason

required

string

properties

object

key

additional properties

object

external_id

string

recorded_at

required

string format: date-time

source

required

string

source_updated_at

string format: date-time

stream

string

scope

required

One of: discriminator: level

object

level

required

string

Allowed value: tenant

Allowed values: tenant

tenant_id

required

string format: uuid

updated_at

required

string format: date-time

version

required

integer

>= 1

has_more

required

boolean

next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string

Example

{
  "data": [
    {
      "object_type": "hospitality.platform_ledger_line",
      "properties": {
        "dispute_leg": "withdrawal",
        "reporting_category": "charge"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Platform ledger line

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required