API ReferencePayouts API

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 Code | Description | |-------------|-------------| | 200 | OK - The list of payouts was successfully retrieved | **Error Responses** | Status Code | Error Code | Description | |-------------|------------|-------------| | 400 | VALIDATION_ERROR | The provided query parameters failed validation | | 400 | INVALID_STATUS_VALUES | One or more invalid status values were provided | | 401 | AUTHENTICATION_ERROR | Authentication credentials are invalid or missing | | 403 | AUTHORIZATION_ERROR | You do not have permission to perform this action | **Example Error Response for Invalid Status** ```http { "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