Skip to navigation

List payouts

View as Markdown

Retrieves a paginated list of payouts. Supports filtering by various criteria including payee name, amount range, creation date, rail type, status, and subaccount.

Filter parameters: amount_gte and amount_lte filter by payout amount in the smallest unit of the currency (same semantics as amount_in_minor_units; for USD, values are in cents).

Success Responses

Status CodeDescription
200OK - The list of payouts was successfully retrieved

Error Responses

Status CodeError CodeDescription
400VALIDATION_ERRORThe provided query parameters failed validation
400INVALID_STATUS_VALUESOne or more invalid status values were provided
401AUTHENTICATION_ERRORAuthentication credentials are invalid or missing
403AUTHORIZATION_ERRORYou do not have permission to perform this action

Example Error Response for Invalid Status

{
"error_code": "INVALID_STATUS_VALUES",
"message": "Invalid status values: invalid_status, another_invalid",
"details": {
"invalid_statuses": ["invalid_status", "another_invalid"],
"valid_statuses": ["approved", "canceled", "created", "debited", "failed", "initiated", "settled"]
}
}

Authentication

x-api-keystring

RootPay API key sent in the x-api-key header. Keys are environment-scoped: live_* for production, test_* for sandbox.

Query parameters

cursorstring or nullOptional

Cursor for pagination. Use the next_cursor from the previous response to get the next page.

limitinteger or nullOptional10-500Defaults to 50
Number of items to return per page. Maximum is 500.
payee_namestring or nullOptional

Filter payouts by a case-insensitive substring match on the payee’s name.

amount_gteinteger or nullOptional>=1

Return payouts whose amount_in_cents is greater than or equal to this value (in cents).

amount_lteinteger or nullOptional>=1

Return payouts whose amount_in_cents is less than or equal to this value (in cents).

created_at_gtedatetime or nullOptional

Return payouts created on or after this date (YYYY-MM-DD).

created_at_ltedatetime or nullOptional

Return payouts created on or before this date (YYYY-MM-DD).

raillist of enums or nullOptional

Filter by rail (standard_ach, same_day_ach, instant_bank, instant_card). Can provide multiple rails as separate parameters (e.g., ?rail=instant_card&rail=instant_bank).

statuslist of enums or nullOptional

Filter by the payout’s latest status. Can provide multiple statuses as separate parameters (e.g., ?status=created&status=approved). Valid values: created, approved, initiated, debited, settled, failed, canceled.

orderenum or nullOptionalDefaults to desc

Sort order by created_at: ‘asc’ for oldest first, ‘desc’ for newest first (default: ‘desc’)

Allowed values:
subaccount_idstring or nullOptionalformat: "uuid"
Filter payouts by subaccount ID. Only returns payouts associated with the specified subaccount.

Response

List of payouts retrieved successfully
datalist of objects
has_moreboolean
total_countinteger or nullOptional>=0Defaults to 0
next_cursorstring or nullOptional
previous_cursorstring or nullOptional