List Payouts

Retrieve historical payouts for your company — quotes, initialized, pending, completed, and failed records all appear here. Supports offset/limit pagination and returns a total_count so you can drive page numbers on your UI.

List payoutsGET/api/payouts
Get payout by IDGET/api/payouts/:id

Request

Page through your company's payout history with GET /api/payouts.

List Payouts

Query Parameters

limitnumberOptional

Maximum number of payouts to return in a single page. Default 20.

offsetnumberOptional

Number of records to skip from the start of the result set. Use with total_count to paginate (e.g. offset=20 for page 2 with limit=20).

Response Fields

data.itemsArray<Payout>

Page of payout records. Each entry uses the same shape as the Initialize / Finalize response — refer to those sections for per-field explanations.

data.total_countInteger

Total number of payouts for your company across all pages.

data.limitInteger

Echo of the limit applied to this page.

data.offsetInteger

Echo of the offset applied to this page.

data.has_moreBoolean

True when offset + limit < total_count — i.e. more records are available beyond this page.

data.items[].statusString

Lifecycle state of the payout: 'QUOTE' (quote created, not initialized), 'INITIATED', 'PENDING' (awaiting settlement), 'COMPLETED', or 'FAILED'.

data.items[].tripObject

Milestone timestamps. 'QUOTE'-status rows only carry quote_at; initialized_at and finalized_at populate as the payout progresses.

metadata.request_idString

Request identifier for log correlation and support.

timestampDate

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

Quote-Only Rows

Payouts you created but never initialized still show up here with status: "QUOTE". They expire at expires_at and are never rerun — treat them as abandoned quotes for reconciliation purposes.

List Payouts - Response

Get Payout by ID

Retrieve a single payout by its internal id (the UUID returned on Initialize / Finalize, not the quote_id). Returns the full payout record including its current lifecycle status, settlement details, and the beneficiary object that was attached at initialize.

Get Payout by ID

Path Parameters

idUUIDRequired

The payout's internal identifier (from data.payout.id on Initialize / Finalize, or data.items[].id on List Payouts). Not the quote_id.

Response

The response shape is identical to Finalize — the wrapped data.payout object with the same settlement, beneficiary, and trip fields. The trip object grows as the payout progresses:

quote_at — set when the quote was created.

initialized_at — set once Initialize succeeds.

processing_start — set when the rail picks up the payout (appears once status: "PROCESSING").

completion_time — set on the terminal COMPLETED or FAILED state.

Field Reference

For per-field explanations, see the Finalize Payout Response section — data.payout.* uses the same shape.

Get Payout by ID - Response