# Query APIs

Building with an AI agent? Start at https://docs.payme.io/agents.md

List sales, transactions, subscriptions, sellers and withdrawals, and look up bank codes: credentials, filters, paging (500 items per page by default), sorting and rate limits.

Use the query APIs to read your data: sales, transactions, subscriptions, sellers and withdrawals, and the bank codes you need when you create a seller. Every call is a `POST` with a JSON body, except `GET /banks/{country_iso_code}`.

| Call | Returns |
|---|---|
| [List sales](/payments/query-apis/post-get-sales) (`POST /get-sales`) | One row per sale (order), with its status, amounts, fees and buyer details |
| [List transactions](/payments/query-apis/post-get-transactions) (`POST /get-transactions`) | One row per money movement: payment, capture, refund, void, chargeback |
| [List subscriptions](/payments/query-apis/post-get-subscriptions) (`POST /get-subscriptions`) | Subscriptions, their status and schedule |
| [List sellers](/payments/query-apis/post-get-sellers) (`POST /get-sellers`) | Your sellers' details, fee settings and balances |
| [List withdrawals](/payments/query-apis/post-get-withdrawals) (`POST /get-withdrawals`) | Past withdrawals (payouts to the seller's bank account) |
| [List future withdrawals](/payments/query-apis/get-future-withdrawals) (`POST /get-future-withdrawals`) | A seller's expected payouts in one currency |
| [List banks](/payments/query-apis/get-banks-country-iso-code) (`GET /banks/{country_iso_code}`) | Bank codes for a country |

To choose the right call for a question (sales in a period, refunds, balances), see [Find the right data](/accepting-payments/reporting/find-the-right-data).

## Credentials

- A **partner** sends `payme_client_key` in the body, or the `PayMe-Partner-Key` header. Without `seller_payme_id`, the query covers all your sellers. To narrow it, send `seller_payme_id` as one MPL or as an array of up to 100 MPLs of your own sellers.
- A **seller** sends its own MPL as `seller_payme_id` in the JSON body, or in the `PayMe-Merchant-Key` header. The results cover that seller only.

See [Authentication](/payments/getting-started/authentication).

## Filters

Every filter is an exact match, except fields that end in `_min` (from, inclusive) and `_max` (to, inclusive). Most filters also take an array of up to 100 values, meaning "any of". Date filters take a single value in `yyyy-mm-dd hh:mm:ss`. Status, currency and payment-method filters take the same values the responses show, for example `completed`, `ILS` or `credit-card`.

| Error | Cause |
|---|---|
| `15` | A date filter isn't in `yyyy-mm-dd hh:mm:ss` |
| `6` | An array has more than 100 values |

## Paging

Results come in pages. `page` starts at `1` (default) and goes up to `1000`. `page_size` is `1`–`500`, default `500`. A call without these fields returns only the first 500 items.

There's no total count: `items_count` is the number of items on this page. Request the next page until `items_count` is lower than `page_size`. An invalid `page` returns error `52`, and an invalid `page_size` returns error `27`, both with HTTP 400. `get-future-withdrawals` and `GET /banks/{country_iso_code}` don't page.

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_created_min": "2026-10-01 00:00:00",
  "sale_created_max": "2026-10-31 23:59:59",
  "page_size": 500,
  "page": 2
}
```

## Sorting

`get-sales`, `get-transactions`, `get-subscriptions`, `get-sellers` and `get-withdrawals` accept `items_order_by_column` (a field to sort by, for example `sale_created` on `get-sales`) and `items_order_by_direction` (`asc`, the default, or `desc`). Any other direction returns error `28`. Without a sort column, the order isn't guaranteed, so set one when you page through results.

## Rate limits

`get-transactions` is rate limited per partner, or per seller when the call has no partner key. `get-future-withdrawals` is rate limited per seller. Over the limit, the call returns HTTP 429 with error `998` and a `Retry-After` header. Wait and retry.

## Timezone

All timestamps returned by the query APIs (`sale_created`, `sale_paid_date`, `sub_next_date` and the others), and the `*_min` / `*_max` filter values you send, are Asia/Jerusalem local time, not UTC. A 2–3 hour offset against a UTC clock is the timezone, not a bug.

## Endpoints

- [List sales](/payments/query-apis/post-get-sales): POST /get-sales
- [List transactions](/payments/query-apis/post-get-transactions): POST /get-transactions
- [List subscriptions](/payments/query-apis/post-get-subscriptions): POST /get-subscriptions
- [List sellers](/payments/query-apis/post-get-sellers): POST /get-sellers
- [List withdrawals](/payments/query-apis/post-get-withdrawals): POST /get-withdrawals
- [List future withdrawals](/payments/query-apis/get-future-withdrawals): POST /get-future-withdrawals
- [List banks](/payments/query-apis/get-banks-country-iso-code): GET /banks/{country_iso_code}