result, with pagination beside it. Each list’s reference says how it’s ordered, which is normally newest first, and which filters it takes.
Cursor Pagination
A list takeslimit and cursor. limit defaults to 25, with a maximum of 100, unless the list documents otherwise.
- Ask for the first page with no
cursor. - While
has_moreistrue, ask for the next page withcursorset tonext_cursor, and the same filters. - On the last page,
has_moreisfalseandnext_cursorisnull.
- A cursor is opaque. Don’t parse it or build one.
- A cursor is only valid with the filters it was issued for. Keep them the same from page to page.
- A page can hold fewer than
limititems, so rely onhas_more, not on the page’s length.
Filtering
Filter on a field by naming it.& always means AND, and comma-separated values within one field mean OR.
completed or pending, with the payment link pl_1.
-
Values with commas. A value containing a comma or a double quote is wrapped in double quotes, with a double quote inside it doubled, as in CSV:
?order_id="Smith, Jones",AcmematchesSmith, JonesorAcme. -
Encoding. Percent-encoding makes no difference:
completed,pendingandcompleted%2Cpendingmean the same, as docreated_at:gteandcreated_at%3Agte. -
One of each. A repeated parameter, such as
?status=completed&status=pending, answers 400. -
Ranges. A range adds an operator after a colon, one of
:gte,:gt,:lteand:lt, and takes one value: -
Money ranges. An amount range gives the value in minor units, with its currency beside it:
?amount:gte=10000¤cy=GBP. A money range withoutcurrencyanswers 400. - Unknown filters answer 400, so a typo never silently returns everything.
-
Values match the values the resource returns, such as
?type=refund.
?is_test=true lists test ones instead.
Searching
A search too complex for a query string, or one carrying personal data, uses a:search action with a JSON body. It takes the list’s filters in the body, and answers as the list does, in the same order. limit and cursor stay in the query string.
"created_at": { "gte": …, "lt": … }. A money range names one currency beside it: "amount": { "gte": 1000 }, "currency": ["GBP"].
POST /merchants/{id}/transactions:search adds q, a contains match on the order ID, the transaction number and the customer’s name and email, and customer_email, an exact match. Neither belongs in a URL, where it would be logged.
Files
GET /merchants/{id}/transactions and POST /merchants/{id}/transactions:search also answer a file, for an accounting tool or a spreadsheet. Ask for one with Accept:
- The whole result. A file holds every record the filters match, in the list’s order. It isn’t paged, so
limit,cursororincludewith a file answers 400. - At most 10,000 rows. A result with more answers 422
EXPORT_TOO_LARGE, never a shorter file. Its detail namesAcceptand gives the limit. Narrow the filters, such as withcreated_atorpayout_id, and ask again. - The same request. A file takes the list’s filters, or the search’s body, and holds the records the JSON would. It takes the list’s permission and the single read’s, such as
transactions:get, since each row is a full representation. An empty result is a file with only the header row. - The full representation. Each row is one record’s full representation, flattened, with its amounts as decimals: Transaction export lists the columns.
- A file comes as an attachment, with
Cache-Control: no-store. A request that fails answers an error, never part of a file.
Accept, or with application/json, a list answers JSON. A format the endpoint doesn’t offer answers 406.