# List sales

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

- Sandbox: `POST https://sandbox.payme.io/api/get-sales`
- Production: `POST https://live.payme.io/api/get-sales`

## Credentials

- Header `PayMe-Partner-Key` (optional): Partner key, instead of `payme_client_key` in the body. Partners only.
- Header `PayMe-Merchant-Key` (optional): A seller's own MPL, instead of `seller_payme_id` in the body.
- Request body field `payme_client_key` (optional): Partner key. Partners only. Can also be sent in the `PayMe-Partner-Key` header. Without `seller_payme_id`, the query covers all your sellers.
- Request body field `seller_payme_id` (optional): The seller's MPL. A partner can send one MPL or an array of up to 100 MPLs of its own sellers to narrow the query. A seller sends its own MPL, here or in the `PayMe-Merchant-Key` header, and gets only its own data.

Returns the sales (orders) of one seller or of all your sellers, with their status, amounts, fees and buyer details. Use it to check where an order stands. For amounts in a period, use [List transactions](/payments/query-apis/post-get-transactions): a refund or chargeback is its own transaction row.

A partner sends `payme_client_key` (or the `PayMe-Partner-Key` header) and, optionally, `seller_payme_id`: one MPL or an array of up to 100 MPLs of its own sellers. Without it, the query covers all your sellers. A seller sends its own MPL as `seller_payme_id` in the body, or in the `PayMe-Merchant-Key` header, and gets only its own data.

Defaults: without `sale_status`, sales in status `initial` (not paid yet) are left out; send `"sale_status": ["initial"]` to see them. Without `sale_type`, tokens (`2`, `12`) and deposits (`6`) are left out. An unknown `sale_status` value is ignored.

Filters are exact matches, except `sale_created_min` / `sale_created_max`. Most filters take a single value or an array of up to 100 values. Dates are `yyyy-mm-dd hh:mm:ss`.

Timestamps in the response, and the date filters you send, are Asia/Jerusalem local time, not UTC. A 2–3 hour offset against a UTC clock is the timezone, not a bug. 

Results come in pages of up to 500 items (default 500). A call without `page` and `page_size` returns only the first 500. Paging, sorting and filter rules are on [Query APIs](/payments/query-apis).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | no | Partner key, instead of `payme_client_key` in the body. Partners only. |
| `PayMe-Merchant-Key` | header | string | no | A seller's own MPL, instead of `seller_payme_id` in the body. |

## Request body

Content type: `application/json`

Every field is optional. Send at least your credentials.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | no | Partner key. Partners only. Can also be sent in the `PayMe-Partner-Key` header. Without `seller_payme_id`, the query covers all your sellers. |
| `seller_payme_id` | string | no | The seller's MPL. A partner can send one MPL or an array of up to 100 MPLs of its own sellers to narrow the query. A seller sends its own MPL, here or in the `PayMe-Merchant-Key` header, and gets only its own data. |
| `seller_id` | string | no | Your own ID for the seller, as sent to create-seller. Partners only. |
| `sale_payme_code` | integer | no | PayMe's numeric sale code. |
| `sale_payme_id` | string | no | PayMe's sale ID, as returned by generate-sale. |
| `transaction_id` | string | no | Your own order ID, as sent to generate-sale. It is not unique, so the call can return several sales. |
| `sale_type` | integer | no | Numeric sale type, see [Sale Types](/payments/codes-statuses/sale-types). Default `[1, 3, 4, 5, 7, 10, 11]`. |
| `sale_parent_code` | integer | no | Code of the parent the sale was created from, for example the template's `sale_payme_code`. |
| `sale_created` | string | no | Exact creation date and time, `yyyy-mm-dd hh:mm:ss`. |
| `sale_created_min` | string | no | Created at or after this time, `yyyy-mm-dd hh:mm:ss`. |
| `sale_created_max` | string | no | Created at or before this time, `yyyy-mm-dd hh:mm:ss`. |
| `sale_status` | string | no | Sale status name, or an array of them, for example `["completed", "refunded"]`. See [Sale Statuses](/payments/codes-statuses/sale-statuses). Default: every status except `initial`. |
| `sale_price` | integer | no | Exact amount, in minor units (`5075` = 50.75). |
| `sale_currency` | string | no | Currency, 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code, for example `ILS`. |
| `sale_payment_method` | string | no | Payment method, for example `credit-card`, `bit`, `apple-pay` or `google-pay`. See [Wallets & APMs](/payments/wallets-apms). |
| `sale_auth_number` | string | no | Authorization number from the card company. |
| `sale_is_3ds` | boolean | no | `true` returns only sales paid with 3D Secure, `false` only sales paid without it. |
| `sale_send_notification` | boolean | no | `true` returns only `initial` or `failed` sales that have a buyer email or phone, for example to send a payment reminder. |
| `buyer_card_mask` | string | no | Masked card number, first 6 and last 4 digits, for example `458045******4580`. |
| `buyer_card_last_four_digits` | string | no | Last four digits of the card. |
| `buyer_card_is_foreign` | boolean | no | `true` returns only sales paid with a foreign card, `false` only local cards. |
| `buyer_email` | string | no | Buyer's email. |
| `buyer_name` | string | no | Buyer's full name. |
| `buyer_phone` | string | no | Buyer's phone number. |
| `buyer_social_id` | string | no | Buyer's national ID number (Israeli sellers). |
| `page` | integer | no | Page number, `1`–`1000`. Default `1`. Out of range returns error `52`. |
| `page_size` | integer | no | Items per page, `1`–`500`. Default `500`. Out of range returns error `27`. |
| `items_order_by_column` | string | no | Field to sort by, for example `sale_created`. Without it, the order isn't guaranteed. A field that doesn't exist fails the call. |
| `items_order_by_direction` | string | no | `asc` (default) or `desc`, in upper or lower case. Used only with `items_order_by_column`. Any other value returns error `28`. |

### Request example

```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",
  "sale_status": [
    "completed",
    "refunded"
  ],
  "items_order_by_column": "sale_created",
  "page": 1,
  "page_size": 500
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/get-sales' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Partner-Key: <PayMe-Partner-Key>' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "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",
  "sale_status": [
    "completed",
    "refunded"
  ],
  "items_order_by_column": "sale_created",
  "page": 1,
  "page_size": 500
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/get-sales", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Partner-Key": "<PayMe-Partner-Key>",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "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",
    "sale_status": [
      "completed",
      "refunded"
    ],
    "items_order_by_column": "sale_created",
    "page": 1,
    "page_size": 500
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/get-sales",
    headers={
        "PayMe-Partner-Key": "<PayMe-Partner-Key>",
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    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",
        "sale_status": [
            "completed",
            "refunded",
        ],
        "items_order_by_column": "sale_created",
        "page": 1,
        "page_size": 500,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "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",
  "sale_status": [
    "completed",
    "refunded"
  ],
  "items_order_by_column": "sale_created",
  "page": 1,
  "page_size": 500
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/get-sales');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Partner-Key: <PayMe-Partner-Key>',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — OK (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `items_count` | integer | Number of items on this page. There is no total count. |
| `items` | array | The sales. |
| `items[].seller_payme_id` | string | The seller's MPL. |
| `items[].seller_id` | string | Your own ID for the seller, or `null`. |
| `items[].sale_payme_id` | string | PayMe's sale ID. |
| `items[].sale_payme_code` | integer | PayMe's numeric sale code. |
| `items[].transaction_id` | string | Your own order ID, as you sent it to generate-sale. It is not unique: several sales can share it. |
| `items[].sale_type` | integer | Numeric sale type, see [Sale Types](/payments/codes-statuses/sale-types). |
| `items[].sale_payment_method` | string | Payment method of the sale, for example `credit-card`. |
| `items[].sale_created` | string | Creation time, `yyyy-mm-dd hh:mm:ss`. |
| `items[].sale_status` | string | Sale status, see [Sale Statuses](/payments/codes-statuses/sale-statuses). |
| `items[].sale_currency` | string | Currency, 3-letter ISO 4217 code. |
| `items[].sale_price` | integer | Amount charged, in minor units (`5075` = 50.75). The sale price when there is no payment yet. |
| `items[].sale_price_after_fees` | string | Net amount after PayMe fees, in minor units, as a numeric string. Final once the transaction is settled. `null` without a payment. |
| `items[].sale_description` | string | What the buyer paid for. |
| `items[].sale_installments` | integer | Number of installments. `null` if the sale has no payment yet. |
| `items[].transaction_first_payment` | string | First installment, in minor units, or the full amount when there are no installments. |
| `items[].transaction_periodical_payment` | string | Each later installment, in minor units. `0` when there are no installments. |
| `items[].transaction_risk_score` | integer | Fraud risk score of the payment, or `null` without a payment. |
| `items[].sale_vat` | string | VAT rate at the time of the sale, as a fraction (`"0.18"` = 18%). |
| `items[].sale_paid_date` | string | When the payment was made, `yyyy-mm-dd hh:mm:ss`. `null` if not paid. |
| `items[].sale_auth_number` | string | Authorization number from the card company. |
| `items[].sale_release_date` | string | When the funds are expected in the seller's balance, `yyyy-mm-dd hh:mm:ss`, or `null`. |
| `items[].sale_error_code` | string | Error code of a failed payment, otherwise `null`. |
| `items[].sale_error_text` | string | Gateway message for the payment. On a failed payment, the error message. |
| `items[].sale_url` | string | Link to the sale's payment page. |
| `items[].sale_is_3ds` | boolean | `true` if the payment used 3D Secure. |
| `items[].sale_fees` | object | Fees on this sale. Rates are percent strings. `*_total` fields are in minor units, without VAT, computed on `sale_price`. |
| `items[].sale_fees.sale_processing_fee` | string | Processing rate, percent of the amount (`"2.50"` = 2.5%). |
| `items[].sale_fees.sale_processing_fee_total` | integer | Processing fee, in minor units. |
| `items[].sale_fees.sale_processing_charge` | string | Fixed processing charge per sale, in major units (`"1.20"` = 1.20). |
| `items[].sale_fees.sale_discount_fee` | string | Discount rate (early settlement of installments) per installment, percent. |
| `items[].sale_fees.sale_discount_fee_total` | integer | Discount fee, in minor units. |
| `items[].sale_fees.sale_rapid_settlement_fee` | string | Rapid settlement rate, percent. |
| `items[].sale_fees.sale_rapid_settlement_fee_total` | integer | Rapid settlement fee, in minor units. |
| `items[].sale_fees.sale_annual_interest_rate` | string | Annual interest rate (percent) behind the discount and rapid settlement fees, or `null`. |
| `items[].sale_fees.sale_market_fee` | string | Platform (market) fee rate, percent of the amount. |
| `items[].sale_fees.sale_market_fee_fixed` | number | Fixed platform fee per sale, in major units. |
| `items[].sale_fees.sale_market_fee_total` | integer | Platform fee, in minor units: the percent part plus the fixed part. |
| `items[].sale_buyer_details` | object | The buyer and the card used. |
| `items[].sale_buyer_details.buyer_card_mask` | string | Masked card number: first 6 and last 4 digits. |
| `items[].sale_buyer_details.buyer_card_expiry` | string | Card expiry, `MMYY`. |
| `items[].sale_buyer_details.buyer_card_brand` | string | Card brand, for example `Visa`. |
| `items[].sale_buyer_details.buyer_card_is_foreign` | boolean | `true` for a card issued outside the seller's country, `false` for a local card. |
| `items[].sale_buyer_details.buyer_name` | string | Buyer's full name. |
| `items[].sale_buyer_details.buyer_email` | string | Buyer's email. |
| `items[].sale_buyer_details.buyer_phone` | string | Buyer's phone number. |
| `items[].sale_buyer_details.buyer_social_id` | string | Buyer's national ID number. |
| `items[].sale_invoices` | object | Invoices for the sale, keyed by invoice document number. Each value has `invoice_doc_number` and `invoice_url`. `{}` when there are none. |

```json
{
  "status_code": 0,
  "items_count": 1,
  "items": [
    {
      "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
      "seller_id": "store-1001",
      "sale_payme_id": "SALE1767-704312AB-CD3FGH12-JKLM4567",
      "sale_payme_code": 98765432,
      "transaction_id": "order-12345",
      "sale_type": 1,
      "sale_payment_method": "credit-card",
      "sale_created": "2026-10-12 15:15:15",
      "sale_status": "completed",
      "sale_currency": "ILS",
      "sale_price": 10000,
      "sale_price_after_fees": "9610",
      "sale_description": "Handmade ceramic bowl",
      "sale_installments": 1,
      "transaction_first_payment": "10000",
      "transaction_periodical_payment": "0",
      "transaction_risk_score": 0,
      "sale_vat": "0.18",
      "sale_paid_date": "2026-10-12 15:16:02",
      "sale_auth_number": "0123456",
      "sale_release_date": "2026-10-19 06:00:00",
      "sale_error_code": null,
      "sale_error_text": "Permitted transaction",
      "sale_url": "https://sandbox.payme.io/sale/generate/SALE1767-704312AB-CD3FGH12-JKLM4567",
      "sale_is_3ds": false,
      "sale_fees": {
        "sale_processing_fee": "2.50",
        "sale_processing_fee_total": 250,
        "sale_processing_charge": "1.20",
        "sale_discount_fee": "0.00",
        "sale_discount_fee_total": 0,
        "sale_rapid_settlement_fee": "0.00",
        "sale_rapid_settlement_fee_total": 0,
        "sale_annual_interest_rate": null,
        "sale_market_fee": "1.50",
        "sale_market_fee_fixed": 0,
        "sale_market_fee_total": 150
      },
      "sale_buyer_details": {
        "buyer_card_mask": "458045******4580",
        "buyer_card_expiry": "1228",
        "buyer_card_brand": "Visa",
        "buyer_card_is_foreign": false,
        "buyer_name": "Israel Israeli",
        "buyer_email": "buyer@example.com",
        "buyer_phone": "0500000001",
        "buyer_social_id": "000000018"
      },
      "sale_invoices": {}
    }
  ]
}
```

### 500 — Error. Most errors return HTTP 500. Paging errors (`52`, `27`) return HTTP 400. The body is the same. See [Errors](/payments/getting-started/errors). (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_code` | integer | PayMe error code. |
| `status_error_details` | string | Error message. |
| `status_additional_info` | string | The field the error refers to, when there is one. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payme_client_key",
  "status_error_code": 1
}
```