List settlements

GET

/v2/payments/collect/settlements

Requires COLLECTIONS_READ, granted by PAYMENTS_READ or COLLECTIONS_WRITE (bundles)

Returns settlements across every account in your business: each is a scheduled payout run or an instant payout of collected funds. Unsettled ones come first, then the most recently settled.

Parameters

Query Parameters

limit

Maximum number of settlements to return.

Type

integer

Example50

Default

50

offset

Number of settlements to skip, for paging.

Type

integer

Example0

Default

0

type

COLLECTION or DISBURSEMENT: only include settlements of that type of payment.

Type

string

Example"COLLECTION"

status

PENDING, SETTLED, FAILED or PARTIALLY_SETTLED.

Type

string

Example"SETTLED"

from

Only count payments received at or after this time, in Unix milliseconds.

Type

integer

Example1792627200000

Format

"int64"

to

Only count payments received before this time, in Unix milliseconds.

Type

integer

Example1792713600000

Format

"int64"

minAmount

Smallest settlement total to include, as a decimal string.

Type

string

Example"100.00"

maxAmount

Largest settlement total to include, as a decimal string.

Type

string

Example"50000.00"

currency

Payout currency.

Type

string

Example"USDC"

query

Free-text search. A date (YYYY-MM-DD) matches that whole day, a number matches a settlement total exactly, and anything else matches the payout currency. Explicit filters take precedence.

Type

string

Example"2026-10-22"

tz

IANA time zone used to interpret a date in query, e.g. Africa/Johannesburg.

Type

string

Example"Africa/Johannesburg"

Responses

OK

Content-Type

application/json

{

"items": [

{

"id": "c4e8a2f6-7b1d-4e3a-8c5f-9d0b1a2c3e4f",

"currency": "USDC",

"totalAmount": "1240.75",

"settledAmount": "1240.75",

"paymentCount": 23,

"status": "SETTLED",

"settledAt": 1792684950000,

"receivedAt": 1792676400000

}

],

"total": 1,

"limit": 50,

"offset": 0

}

Samples

Errors

HTTP	Error	When
400	BAD_REQUEST	A query parameter or field is invalid.
403	-16098PAYMENTS_USER_ACCESS_NOT_CONFIGURED	Payments haven't been set up for your business yet.
500	INTERNAL_ERROR	Unexpected error in the payments service.
502	-16097EXCHANGE_API_ERROR	The payments service failed to process the request.
502	EXCHANGE_API_ERROR	The payments service couldn't complete the request. Try again later.
503	-16099PAYMENTS_BACKEND_PROXY_DISABLED	Payments endpoints are temporarily unavailable.

Plus the errors common to all signed endpoints.