Pagination and expand

Walk long lists with cursors, filter them by date, and load related objects in the same request.

Lists

Every GET on a collection (/v1/payments, /v1/receipts, /v1/deposits, /v1/payment_links, /v1/customers, /v1/events, /v1/webhook_endpoints, /v1/cards, /v1/devices) answers a list object, newest first:

JSON

{
  "object": "list",
  "url": "/v1/payments",
  "has_more": true,
  "data": [{ "id": "pay_8xkq2LmZr0Pa1Bcd", "object": "payment" }]
}

Lists
Parameter	Description
`limit`	Objects per page, 1 to 100. Default 10.
`starting_after`	The id of the last object of the page you have: the next page holds older objects.
`ending_before`	The id of the first object of the page you have: the page before it, toward newer objects.
`created`	A unix second, or a range: `created[gte]=1793000000&created[lt]=1793086400` (`gt`, `gte`, `lt`, `lte`).

Send starting_after or ending_before, not both. A cursor that names no object of the list is resource_missing.

Walking every page

curl -G https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -d limit=100 \
  -d status=succeeded \
  -d "created[gte]=1793000000" \
  -d starting_after=pay_8xkq2LmZr0Pa1Bcd

Each list has its own filters: payments by status, customer and reference; deposits by status, payment and card; payment links by active; customers by phone and email; events by type (a type or payment.*) and types[]; cards by status; devices by health. The API reference lists them per endpoint.

Expand

Some fields hold the id of another object. Ask for the object itself with expand[]:

Expand
Object	Expandable
`payment`	`customer` (the customer object instead of its id), `deposits` (every matched deposit as a full object instead of the summaries), `receipts` (its receipts, newest first, up to 100; a restricted key needs `receipts` read)
`payment_link`	`card` (the override card instead of its id)

curl -G https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd \
  -H "Authorization: Bearer sk_test_…" \
  -d "expand[]=customer" \
  -d "expand[]=deposits"

On a list, prefix the field with data. (expand[]=data.customer). On a POST, send expand in the body. At most 10 expansions per request; anything else is parameter_invalid.

Without expand, a payment's deposits holds up to 10 summaries (id, amount, created) with has_more when there are more, and the payment has no receipts field at all.