Read a merchant account's balance and next payout

GET

/v1/merchant-accounts/{merchant_account_id}/balance

curl --request GET \
  --url https://api.aerandil.com/v1/merchant-accounts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/balance \
  --header 'Authorization: Bearer <token>'

• Production API

The hotel’s money at Stripe now, read live as the hotel (GET /v1/balance with Stripe-Account): available and pending per currency (connect_reserved is the platform’s field, never the hotel’s). next_payout is the payout Stripe has already made when there is one (basis: payout — its arrival date and amount), else the earliest day the hotel’s pending balance transactions become available and how much does that day (basis: pending_balance); the bank adds its own day or two. in_flight lists the payouts still on their way. The general manager’s read (analytics:read), or the operator’s; a desk session bound to another house is refused.

Authorizations

• aerandil_oauth
  analytics:read
• aerandil_oauth
  tenant_admin:write

Parameters

Path Parameters

merchant_account_id

required

string format: uuid

The property’s merchant account.

Responses

200

The balance and the next payout.

Media typeapplication/json

object

available

required

Array<object>

object

amount

required

string format: decimal

currency

required

string

in_flight

required

Array<object>

object

merchant_account_id

required

string format: uuid

next_payout

required

object

amount

string | null format: decimal

available_on

Forecast only: the earliest day that money becomes available (Stripe’s available_on).

string | null format: date

basis

string

Allowed values: payout pending_balance

currency

string | null

date

The day the money is paid out: a payout’s arrival day, or — forecast — the account’s own payout day for its pending money (the anchor day of a weekly or monthly schedule); null for a manual account, which Stripe pays out only when asked.

string | null format: date

interval

Forecast only: the account’s payout interval as Stripe reports it (daily, weekly, monthly, manual), null when not yet read.

string | null

payout_reference

string | null

observed_at

string format: date-time

pending

required

Array<object>

object

amount

required

string format: decimal

currency

required

string

property_id

string format: uuid

Example

{
  "next_payout": {
    "basis": "payout"
  }
}

Headers

Cache-Control

string

Always no-store. Object and link state is live data and is never cacheable.

403

The bearer authenticated but does not hold the scope this operation requires.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

404

No such object in the caller’s tenant — which is also the answer when it exists in another tenant, by design.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

501

No card rail is configured on this deployment.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

503

rail_unavailable — the card processor could not be reached (a transport failure, a 5xx, a 429, or this request’s key still running at the processor). The balance was not read. Try again after Retry-After.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object

error

required

object

code

required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string

instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string

message

required

Human-readable explanation of the failure.

string

parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Example^generated

{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

Headers

Retry-After

integer

Seconds to wait before trying the same request again (RFC 9110 §10.2.3) — the queue’s first backoff.