# Find the right data

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

## Related

- [Reporting across your sellers](/marketplaces-and-platforms/reporting/reporting-across-your-sellers)
- [Reconcile sales and withdrawals](/accepting-payments/reporting/reconcile-sales-and-withdrawals)

## Choose a query

Each row names the call to make, the filters to send and the field that holds the answer. All calls are `POST` with a JSON body. A seller sends its own `seller_payme_id` on every request. A partner adds `seller_payme_id` to narrow a query to some of its sellers.

| Question | Query API | Filters | Read from each item |
| --- | --- | --- | --- |
| What volume did a seller process on a given day? | [get-transactions](/payments/query-apis/post-get-transactions) | `transaction_status`: `validated`, `sale_currency`, `transaction_created_min`, `transaction_created_max` | Sum of `transaction_price` |
| How many payments were there, and what was the average? | [get-transactions](/payments/query-apis/post-get-transactions) | `transaction_status`: `validated`, `sale_currency`, `transaction_created_min`, `transaction_created_max` | Count the items, then divide the sum of `transaction_price` by the count |
| Which refunds happened in a period? | [get-transactions](/payments/query-apis/post-get-transactions) | `transaction_status`: `["refunded", "p-refund"]`, `transaction_created_min`, `transaction_created_max` | `transaction_price`, `sale_payme_id`, `transaction_action` |
| Which chargebacks happened in a period? | [get-transactions](/payments/query-apis/post-get-transactions) | `transaction_status`: `["chargeback", "partial-chargeback"]`, `transaction_created_min`, `transaction_created_max` | `transaction_price`, `sale_payme_id`, `transaction_action` |
| What method did the buyer pay with? | [get-transactions](/payments/query-apis/post-get-transactions) | `sale_payme_id` | `transaction_payment_method`, and for cards `sale_buyer_details.buyer_card_brand` |
| What is the status of an order? | [get-sales](/payments/query-apis/post-get-sales) | `transaction_id` (your order ID; can match several sales) or `sale_payme_id` | `sale_status`, `sale_paid_date` |
| When will a sale's funds be available? | [get-sales](/payments/query-apis/post-get-sales) | `sale_payme_id` | `sale_release_date` |
| Which subscriptions are active? | [get-subscriptions](/payments/query-apis/post-get-subscriptions) | `sub_status`: `2` | `sub_price`, `sub_currency`, `sub_next_date` |
| Which subscriptions are failing? | [get-subscriptions](/payments/query-apis/post-get-subscriptions) | `sub_status`: `[4, 7]` | `sub_error_text`, `sub_next_date` |
| What is the balance available to withdraw? | [get-sellers](/payments/query-apis/post-get-sellers) | `seller_payme_id` (don't send `api_mode` `slim`, which leaves out `seller_wallets`) | `seller_wallets.<currency>.wallet_releasable` |
| What payouts were made? | [get-withdrawals](/payments/query-apis/post-get-withdrawals) | `withdrawal_created_min`, `withdrawal_created_max`, `withdrawal_currency` | `withdrawal_total`, `withdrawal_created` |
| What payouts are coming up? | [get-future-withdrawals](/payments/query-apis/get-future-withdrawals) | `seller_payme_id`, `currency` (both required) | `created_at` (expected date), `total`. An item with `end_time` `-1` is a summary and has no expected date |

Status values are listed on [Sale Statuses](/payments/codes-statuses/sale-statuses), [Transaction Statuses](/payments/codes-statuses/transaction-statuses) and [Subscription Statuses](/payments/codes-statuses/subscription-statuses). To filter on a partially refunded transaction, send the value `p-refund`.

## Sale or transaction

A sale is one order; a transaction is one movement of money on it, such as the payment, a refund or a chargeback.

Use `get-sales` to see where an order stands. Use `get-transactions` for amounts in a period, because a refund or chargeback is its own row with its own date. Refund and chargeback rows hold a positive `transaction_price`, so subtract them yourself.

## Example: a seller's volume for one day

Send a request to `https://sandbox.payme.io/api/get-transactions` (production: `https://live.payme.io/api/get-transactions`):

```json
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "transaction_status": "validated",
  "sale_currency": "ILS",
  "transaction_created_min": "2026-11-03 00:00:00",
  "transaction_created_max": "2026-11-03 23:59:59",
  "page_size": 500,
  "page": 1
}
```

Add up `transaction_price` across every page. Amounts are in minor units, so `10000` means 100.00. Query one currency at a time, since `transaction_price` is in the sale's currency.

## Dates and pages

- **Timezone:** timestamps and the `*_min` / `*_max` filters are [Asia/Jerusalem local time](/payments/query-apis#timezone), not UTC. Send them as `yyyy-mm-dd hh:mm:ss`.
- **Pages:** `page_size` goes up to 500, which is also the default, and `page` starts at 1 and goes up to 1000. Without them, you get only the first 500 items. For larger results, narrow the dates. `items_count` counts the items on the current page, not the full result, so keep requesting pages until `items_count` is lower than `page_size`. `get-future-withdrawals` does not page.
- **Rate limits:** `get-transactions` and `get-future-withdrawals` are rate limited. On HTTP 429 with code `998`, wait and retry; see [Query APIs](/payments/query-apis#rate-limits).

## Who can call what

Credentials are explained on [Authentication](/payments/getting-started/authentication).

| Query API | As a seller (`seller_payme_id`) | As a partner (`payme_client_key`) |
| --- | --- | --- |
| `get-sales`, `get-transactions`, `get-subscriptions`, `get-sellers`, `get-withdrawals` | That seller's data | All the partner's sellers, or the sellers named in `seller_payme_id` |
| `get-future-withdrawals` | That seller's data | One seller per request; `seller_payme_id` is required |

A seller sends its own MPL as `seller_payme_id` in the JSON body, as a single value, or in the `PayMe-Merchant-Key` header. The results cover that seller only. A partner sends `payme_client_key` in the body or the `PayMe-Partner-Key` header, and can send `seller_payme_id` as an array of up to 100 MPLs of its own sellers. Every item carries its `seller_payme_id`, so a partner can group the results by seller.