Skip to main content
A list returns an array of one representation in result, with pagination beside it. Each list’s reference says how it’s ordered, which is normally newest first, and which filters it takes.
The resource above is shortened.

Cursor Pagination

A list takes limit and cursor. limit defaults to 25, with a maximum of 100, unless the list documents otherwise.
  1. Ask for the first page with no cursor.
  2. While has_more is true, ask for the next page with cursor set to next_cursor, and the same filters.
  3. On the last page, has_more is false and next_cursor is null.
  • 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 limit items, so rely on has_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.
That matches a status of 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",Acme matches Smith, Jones or Acme.
  • Encoding. Percent-encoding makes no difference: completed,pending and completed%2Cpending mean the same, as do created_at:gte and created_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, :lte and :lt, and takes one value:
  • Money ranges. An amount range gives the value in minor units, with its currency beside it: ?amount:gte=10000&currency=GBP. A money range without currency answers 400.
  • Unknown filters answer 400, so a typo never silently returns everything.
  • Values match the values the resource returns, such as ?type=refund.
An unfiltered list returns everything you can read, unless it documents otherwise. Transactions and payment links are the exception: a list holds live records, and ?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.
In the body, a filter that takes several values takes an array, and a range is an object of its operators, such as "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, cursor or include with a file answers 400.
  • At most 10,000 rows. A result with more answers 422 EXPORT_TOO_LARGE, never a shorter file. Its detail names Accept and gives the limit. Narrow the filters, such as with created_at or payout_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.
With no Accept, or with application/json, a list answers JSON. A format the endpoint doesn’t offer answers 406.

Totals

A list doesn’t return totals, so listing stays cheap. To total a merchant’s balance in one currency, see Reconcile payouts.