---
title: "Query payouts"
method: POST
path: "/v2/payouts/query"
tags: ["Payouts"]
---

# Query payouts

`POST /v2/payouts/query`

## Request

- Base URL: `https://api.getpaid.io`
- URL: `https://api.getpaid.io/v2/payouts/query`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://auth.getpaid.io/oauth/token` scopes: `payouts:read`
- TypeScript: <https://skmtc.dev/getpaid/apis/getpaid-api/docs/v2/payouts/query/post.ts> (a function with typed inputs; its response is checked against the schema)

List payouts across all accounts available to the caller, or restrict the result to one account.

A payout is always linked to one account. This endpoint intentionally supports querying
across accounts so platforms can reconcile payouts for all of their sellers.

## Headers

- `Getpaid-Idempotency-Key` string, required

## Request body

- QueryPayoutsRequest
  - `type` 'payouts', required: The type of the Getpaid solution resources to query. Some query endpoints infer the resource type from the request path. In those cases, if this field is set, it must match the resource targeted by the request URL.
  - `first` integer: Pagination. The number of elements that will be retrieved.
  - `after` string: Pagination. The `cursor` from next page will be retrieved.
  - `filters` object: Filtering payouts.
    - `account_id` string, id: The unique identifier of the account.
    - `reference` string: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `statuses` PayoutStatus[]: The list of payout statuses to filter by.
  - `sorts` object[]: Fields to sort payouts by. If not set, payouts are sorted by creation date descending.
    - `field` 'created_at', required: The field to sort by. Each field available can only be used once in the list.
    - `direction` 'ascending' | 'descending', required: The sort direction

## Response `200`

OK

- QueryPayoutsResponse
  - `type` 'payouts', required
  - `cursor` string: The cursor to the last item. If non-empty, can be used to fetch the next page. If not set, there is no more elements.
  - `data` object[], required: The list of queried elements.
    - `id` string, id, required: The unique identifier of the payout.
    - `reference` string, required: An identifier in your system. It is recommended to make it unique but the uniqueness is not enforced by the solution.
    - `account` SellerRef, required: A reference to the seller account.
      - `id` string, id, required: The unique identifier of the account.
      - `legal_name` string, required: The legal name of the account.
    - `status` 'initiated' | 'movements_assigned' | 'transfer_initiated' | 'completed' | 'rejected', required: The status of the payout. See the [list, transitions, and description of each status](/manage-funds/payouts/lifecycle) for more details.
    - `reason` PayoutReason: Reason of the status of the resource when it requires additional steps or is a failure state.
      - `code` string, required: Code to identify the cause of the status of the resource.
      - `description` string, required: Human-readable description of the reason for the status of the resource.
    - `amount` integer, required: The payment amount in the minor currency unit (e.g. 100 cents for 1 EUR).
    - `currency` string, currency, required: The processing currency code according to the [ISO-4217 standard](https://en.wikipedia.org/wiki/ISO_4217)
    - `created_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `updated_at` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
    - `cutoff` PayoutCutoff, required: Time range used to determine which movements are included in the payout. The range is half-open: `from` is inclusive and `to` is exclusive.
      - `from` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.
      - `to` string, date-time, required: UTC timestamp in ISO 8601 format with milliseconds ([RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html)). Always includes the 'Z' UTC indicator.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `422`: Invalid Parameters
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/getpaid/apis/getpaid-api.md) - [All operations](https://skmtc.dev/getpaid/apis/getpaid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getpaid/apis/getpaid-api/revisions/458eae3d49ad?raw)