Skip to content
aerandil.com
GitHub

Search Payout

POST
/v1/object-types/hospitality.payout/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.payout/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.

A payout from a hotel’s processor balance to its bank (Stripe’s po_…), mirrored from the processor’s events on the property’s merchant account. status is the processor’s own and paid is provisional — a payout can fail after it reads as paid. Once the processor has itemised it, its balance transactions are recorded as payout_lines, each matched to the ledger payment it came from, and the payout carries the counts: lines, matched, the net of what did not match, and the fees taken.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/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 status reconciliation_status currency arrival_date initiated_at failure_code failure_message failed_at line_count matched_count reconciled_at money_line_count unmatched_count

Responses

Section titled “Responses”

200

Section titled “200”

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

Media typeapplication/json
object
data
required
Array<object>
object
created_at
required
string format: date-time
id
required
string format: uuid
object_type
required
Allowed value: hospitality.payout
properties
required
object
amount
required
Payout amount

What the payout sends to the bank, as the processor states it (net of everything the lines carried)

object
amount
required
string format: decimal
currency
required
string format: iso-4217
arrival_date
The day the processor expects the money in the bank
string format: date
automatic
required
Whether the processor paid it out on its schedule. A manual payout cannot be itemised
boolean
currency
required
The payout's currency (ISO 4217, upper case)
string
failed_at
When the ledger heard the payout failed
string format: date-time
failure_code
The processor's reason the payout failed (`account_closed`, `no_account`, …)
string
failure_message
The processor's words for the failure
string
fees_total
Payout fees total

The processor’s fees the lines carried: their fee fields plus any separate fee lines

object
amount
required
string format: decimal
currency
required
string format: iso-4217
id
required
Payout id
string
initiated_at
required
When the processor created the payout
string format: date-time
line_count
required
Balance transactions recorded against the payout
integer
matched_count
required
Of those, the lines matched to a ledger payment
integer
merchant_account_id
required
The merchant account whose balance paid out (its object id) — the payout_for_merchant_account edge's target
string
money_line_count
Of the lines, those that are a guest's money and should match a payment (every category bar `fee`, `payout` and `payout_reversal`)
integer
property_id
required
The house the merchant account settles for (its object id)
string
psp_reference
required
The processor's id for the payout (Stripe `po_…`) — the replay key every event about it lands on. An identifier, not a credential.
string
reconciled_at
When the ledger finished recording the lines
string format: date-time
reconciliation_difference
Payout reconciliation difference

The payout’s amount less the net of every line bar the payout’s own — zero when the lines add up to what the bank was sent; otherwise the payout is completed_with_difference

object
amount
required
string format: decimal
currency
required
string format: iso-4217
reconciliation_status
required
Whether the payout's lines are on the ledger: `in_progress` while the processor itemises it, `not_started` once it has and the ledger has not, `completed` once recorded and adding up to the payout, `completed_with_difference` once recorded but not adding up (`reconciliation_difference`), `not_applicable` for a manual payout
string
Allowed values: not_started in_progress completed not_applicable completed_with_difference
reversed_total
Payout reversed total

The net of the payout_reversal lines: an earlier failed payout’s money, returned to the balance and sent again in this one

object
amount
required
string format: decimal
currency
required
string format: iso-4217
status
required
The processor's payout status; `paid` is provisional
string
Allowed values: pending in_transit paid failed canceled
unmatched_amount
Payout unmatched amount

The size of the money lines (charges, refunds, disputes, transfers) that matched no ledger payment — the sum of their nets’ magnitudes, so £50 in and £50 out unmatched is £100, not nothing; computed from the lines, never typed

object
amount
required
string format: decimal
currency
required
string format: iso-4217
unmatched_count
Of the money lines, those that matched no ledger payment
integer
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.payout",
      "properties": {
        "reconciliation_status": "not_started",
        "status": "pending"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.