# List sellers

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

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

## 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 your sellers with their personal, business and bank details, fee settings and wallet balances. Use it to check a seller's balance or approval, or to list the sellers created in a period. Only seller accounts are returned, not partner or system accounts.

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. The response contains ID numbers and bank details: keep it on your server.

Set `api_mode` to `slim` for a faster call on long lists. It leaves out `seller_wallets`, `seller_monthly_invoices` and `seller_monthly_balance_authorizations`. Omit `api_mode` for the default, which includes them.

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

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. |
| `api_mode` | string | no | `slim` returns seller details only, without `seller_wallets`, `seller_monthly_invoices` and `seller_monthly_balance_authorizations`. Omit it for the default, which includes them. |
| `seller_created` | string | no | Exact creation date and time, `yyyy-mm-dd hh:mm:ss`. |
| `seller_created_min` | string | no | Created at or after this time, `yyyy-mm-dd hh:mm:ss`. |
| `seller_created_max` | string | no | Created at or before this time, `yyyy-mm-dd hh:mm:ss`. |
| `seller_first_name` | string | no | First name of the seller's owner. |
| `seller_last_name` | string | no | Last name of the seller's owner. |
| `seller_social_id` | string | no | National ID number of the seller's owner. |
| `seller_email` | string | no | Seller's email. |
| `seller_phone` | string | no | Seller's phone number. |
| `seller_contact_email` | string | no | Contact email shown to buyers. |
| `seller_contact_phone` | string | no | Contact phone shown to buyers. |
| `seller_inc` | integer | no | Incorporation type, see [Seller Incorporation Types (IL)](/marketplaces-and-platforms/seller-reference/seller-incorporation-types-il). `0` and `1` both mean Individual. |
| `seller_inc_code` | string | no | Business registration number (ח.פ or ע.מ). |
| `seller_merchant_name` | string | no | Seller's business name. |
| `fee_market_fee` | number | no | The seller's default platform (market) fee, percent of the sale price. |
| `seller_active` | boolean | no | `true` returns only active sellers, `false` only inactive ones. |
| `seller_approved` | boolean | no | `true` returns only sellers approved by PayMe, `false` only sellers not approved yet. |
| `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. 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_created_min": "2026-10-01 00:00:00",
  "seller_created_max": "2026-10-31 23:59:59",
  "seller_approved": true,
  "api_mode": "slim"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/get-sellers' \
  -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_created_min": "2026-10-01 00:00:00",
  "seller_created_max": "2026-10-31 23:59:59",
  "seller_approved": true,
  "api_mode": "slim"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/get-sellers", {
  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_created_min": "2026-10-01 00:00:00",
    "seller_created_max": "2026-10-31 23:59:59",
    "seller_approved": true,
    "api_mode": "slim"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/get-sellers",
    headers={
        "PayMe-Partner-Key": "<PayMe-Partner-Key>",
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "payme_client_key": "XXXXXXXX",
        "seller_created_min": "2026-10-01 00:00:00",
        "seller_created_max": "2026-10-31 23:59:59",
        "seller_approved": True,
        "api_mode": "slim",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "payme_client_key": "XXXXXXXX",
  "seller_created_min": "2026-10-01 00:00:00",
  "seller_created_max": "2026-10-31 23:59:59",
  "seller_approved": true,
  "api_mode": "slim"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/get-sellers');
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 sellers. |
| `items[].seller_payme_id` | string | The seller's MPL. |
| `items[].seller_id` | string | Your own ID for the seller, or `null`. |
| `items[].seller_created` | string | Creation time, `yyyy-mm-dd hh:mm:ss`. |
| `items[].seller_active` | boolean | `true` if the seller is active. |
| `items[].seller_approved` | boolean | `true` once PayMe has approved the seller. Withdrawals need approval. |
| `items[].seller_approved_date` | string | When PayMe approved the seller, or `null`. |
| `items[].seller_is_deferred` | boolean | `true` if the seller's account type is Deferred. |
| `items[].seller_withdrawal_plan` | integer | Withdrawal plan: `1` manual, `2` daily, `3` monthly. |
| `items[].seller_withdrawal_date` | integer | Day of the month of the payout when the plan is `3`, otherwise `null`. |
| `items[].seller_allow_foreign_cards` | boolean | `true` if the seller accepts foreign cards. |
| `items[].seller_personal_details` | object | The seller's owner (primary individual). |
| `items[].seller_personal_details.seller_first_name` | string | First name. |
| `items[].seller_personal_details.seller_last_name` | string | Last name. |
| `items[].seller_personal_details.seller_first_name_en` | string | First name in English. |
| `items[].seller_personal_details.seller_last_name_en` | string | Last name in English. |
| `items[].seller_personal_details.seller_social_id` | string | National ID number. |
| `items[].seller_personal_details.seller_social_id_country` | string | Country that issued the ID, ISO 3166-1 alpha-2 code. |
| `items[].seller_personal_details.seller_social_id_issued` | string | ID issue date, `yyyy-mm-dd`. |
| `items[].seller_personal_details.seller_birthdate` | string | Date of birth, `yyyy-mm-dd`. |
| `items[].seller_personal_details.seller_date_of_birth` | string | Same as `seller_birthdate`. Kept for older integrations. |
| `items[].seller_personal_details.seller_gender` | integer | `0` male, `1` female, `2` other. |
| `items[].seller_personal_details.seller_email` | string | Seller's email. |
| `items[].seller_personal_details.seller_phone` | string | Seller's phone number. |
| `items[].seller_personal_details.seller_has_criminal_record` | boolean | The owner's answer to the criminal record question, or `null`. |
| `items[].seller_business_details` | object | The business and its bank account. |
| `items[].seller_business_details.seller_inc` | integer | Incorporation type, see [Seller Incorporation Types (IL)](/marketplaces-and-platforms/seller-reference/seller-incorporation-types-il). `0` for Individual. |
| `items[].seller_business_details.seller_inc_code` | string | Business registration number (ח.פ or ע.מ). |
| `items[].seller_business_details.seller_registration_date` | string | Business registration date, `yyyy-mm-dd`, or `null`. |
| `items[].seller_business_details.seller_merchant_name` | string | Business name. |
| `items[].seller_business_details.seller_merchant_name_en` | string | Business name in English. |
| `items[].seller_business_details.seller_dba` | string | Trading name (doing business as). |
| `items[].seller_business_details.seller_dba_en` | string | Trading name in English. |
| `items[].seller_business_details.seller_business_type` | integer | Business field code (`seller_person_business_type` on create-seller). See [MCC List](/marketplaces-and-platforms/seller-reference/mcc-list). |
| `items[].seller_business_details.seller_site_url` | string | Seller's website. |
| `items[].seller_business_details.seller_description` | string | Description of the business. |
| `items[].seller_business_details.seller_retail_type` | integer | `1` card not present (online), `2` card present, `4` phone or mail order (MOTO). |
| `items[].seller_business_details.seller_contact_email` | string | Contact email shown to buyers. |
| `items[].seller_business_details.seller_contact_phone` | string | Contact phone shown to buyers. |
| `items[].seller_business_details.seller_bank_account_code` | string | Bank code (`seller_bank_code` on create-seller). See [Banks in Israel](/payments/codes-statuses/banks-in-israel). |
| `items[].seller_business_details.seller_bank_account_branch` | string | Bank branch (`seller_bank_branch` on create-seller). |
| `items[].seller_business_details.seller_bank_account_number` | string | Bank account number. |
| `items[].seller_business_details.seller_bank_routing_number_foreign` | string | Routing number of a bank account abroad, or `null`. |
| `items[].seller_business_details.seller_bank_account_number_foreign` | string | Number of a bank account abroad, or `null`. |
| `items[].seller_business_details.seller_need_foreign_currency` | boolean | The seller's answer: needs to process foreign currencies. `null` if not answered. |
| `items[].seller_business_details.seller_was_rejected_by_bank` | boolean | The seller's answer: was rejected by a bank before. `null` if not answered. |
| `items[].seller_business_details.seller_bank_rejection_reason` | string | The reason the seller gave for the bank rejection, or `null`. |
| `items[].seller_business_details.seller_source_of_finance` | string | Source of the business's funds, as a name, or `null`. |
| `items[].seller_business_details.seller_required_service_type` | string | Service type the seller asked for, as a name, or `null`. |
| `items[].seller_business_details.seller_account_type` | string | Account type: `Deferred`, `Restricted`, `Unrestricted`, `Accounting` or `POS`. |
| `items[].seller_address` | object | The business address. |
| `items[].seller_address.seller_address_city` | string | City. |
| `items[].seller_address.seller_address_street` | string | Street. |
| `items[].seller_address.seller_address_street_number` | string | Street number. |
| `items[].seller_address.seller_address_country` | string | Country, ISO 3166-1 alpha-2 code. |
| `items[].seller_fees` | object | This seller's fee settings. Rates are percent strings (`"2.50"` = 2.5%), and `*_processing_charge` is a fixed charge in major units. `foreign` is for foreign cards, `forcurr` for sales in a foreign currency. |
| `items[].seller_fees.fee_market_fee` | string | Default platform (market) fee you take on this seller's sales, percent. |
| `items[].seller_fees.fee_default_processing_fee` | string | Processing rate, percent. |
| `items[].seller_fees.fee_default_processing_charge` | string | Fixed charge per transaction, in major units. |
| `items[].seller_fees.fee_default_rapid_settlement_fee` | string | Rapid settlement rate, percent. |
| `items[].seller_fees.fee_default_discount_fee` | string | Discount rate (early settlement of installments) per installment, percent. |
| `items[].seller_fees.fee_default_premium_processing_fee` | string | Processing rate for premium cards, percent. |
| `items[].seller_fees.fee_corporate_processing_fee` | string | Processing rate for corporate cards, percent. |
| `items[].seller_fees.fee_foreign_processing_fee` | string | Processing rate for foreign cards, percent. |
| `items[].seller_fees.fee_foreign_processing_charge` | string | Fixed charge per transaction on foreign cards, in major units. |
| `items[].seller_fees.fee_foreign_rapid_settlement_fee` | string | Rapid settlement rate for foreign cards, percent. |
| `items[].seller_fees.fee_foreign_discount_fee` | string | Discount rate for foreign cards, percent. |
| `items[].seller_fees.fee_foreign_premium_processing_fee` | string | Processing rate for foreign premium cards, percent. |
| `items[].seller_fees.fee_foreign_corporate_processing_fee` | string | Processing rate for foreign corporate cards, percent. |
| `items[].seller_fees.fee_forcurr_processing_fee` | string | Processing rate for sales in a foreign currency, percent. |
| `items[].seller_fees.fee_forcurr_processing_charge` | string | Fixed charge per transaction in a foreign currency, in major units. |
| `items[].seller_fees.fee_forcurr_rapid_settlement_fee` | string | Rapid settlement rate for sales in a foreign currency, percent. |
| `items[].seller_fees.fee_forcurr_discount_fee` | string | Discount rate for sales in a foreign currency, percent. |
| `items[].seller_fees.fee_forcurr_premium_processing_fee` | string | Processing rate for premium cards in a foreign currency, percent. |
| `items[].seller_fees.fee_forcurr_corporate_processing_fee` | string | Processing rate for corporate cards in a foreign currency, percent. |
| `items[].seller_currencies` | array | Currencies the seller can sell in, as ISO 4217 codes. |
| `items[].seller_processing_percent` | number | Share of the seller's processing limit used, percent. |
| `items[].seller_processing_limit` | integer | The seller's processing limit. |
| `items[].seller_timezone` | string | The seller's timezone. |
| `items[].seller_display_language` | string | The seller's language, for example `he` or `en`. |
| `items[].seller_wallets` | object | Balances, one entry per currency, keyed by the currency code. Not returned with `api_mode` `slim`. |
| `items[].seller_wallets.ILS` | object | The wallet in this currency. |
| `items[].seller_wallets.ILS.wallet_currency` | string | Currency of the wallet. |
| `items[].seller_wallets.ILS.wallet_total` | integer | Everything PayMe holds for the seller in this currency, in minor units. |
| `items[].seller_wallets.ILS.wallet_releasable` | integer | The part past its release date, available to withdraw, in minor units. |
| `items[].seller_monthly_invoices` | object | PayMe's monthly invoices to the seller, keyed by invoice document number. Not returned with `api_mode` `slim`. |
| `items[].seller_monthly_invoices.1234` | object | One invoice. |
| `items[].seller_monthly_invoices.1234.invoice_reference` | string | Month the invoice covers, `yyyy-mm`. |
| `items[].seller_monthly_invoices.1234.invoice_created` | string | Invoice date, `yyyy-mm-dd`. |
| `items[].seller_monthly_invoices.1234.invoice_doc_number` | string | Invoice document number. |
| `items[].seller_monthly_invoices.1234.invoice_currency` | string | Invoice currency. |
| `items[].seller_monthly_invoices.1234.invoice_url` | string | Link to the invoice PDF. |
| `items[].seller_monthly_invoices.1234.invoice_details_url` | string | Link to the invoice details page. |
| `items[].seller_monthly_balance_authorizations` | object | Links to the seller's monthly balance statements, keyed by year and then by month (`1`–`12`). A month appears from the 10th of the following month. Not returned with `api_mode` `slim`. |

```json
{
  "status_code": 0,
  "items_count": 1,
  "items": [
    {
      "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
      "seller_id": "store-1001",
      "seller_created": "2026-01-01 15:15:15",
      "seller_active": true,
      "seller_approved": true,
      "seller_approved_date": "2026-01-05 10:00:00",
      "seller_is_deferred": false,
      "seller_withdrawal_plan": 1,
      "seller_withdrawal_date": null,
      "seller_allow_foreign_cards": true,
      "seller_personal_details": {
        "seller_first_name": "Dana",
        "seller_last_name": "Levi",
        "seller_first_name_en": "Dana",
        "seller_last_name_en": "Levi",
        "seller_social_id": "000000018",
        "seller_social_id_country": "IL",
        "seller_social_id_issued": "2015-02-01",
        "seller_birthdate": "1989-05-06",
        "seller_date_of_birth": "1989-05-06",
        "seller_gender": 1,
        "seller_email": "dana@example.com",
        "seller_phone": "0500000005",
        "seller_has_criminal_record": false
      },
      "seller_business_details": {
        "seller_inc": 2,
        "seller_inc_code": "000000018",
        "seller_registration_date": null,
        "seller_merchant_name": "Dana Ceramics",
        "seller_merchant_name_en": "Dana Ceramics",
        "seller_dba": "Dana Ceramics",
        "seller_dba_en": "Dana Ceramics",
        "seller_business_type": 10004,
        "seller_site_url": "https://www.example.com",
        "seller_description": "Handmade ceramics",
        "seller_retail_type": 1,
        "seller_contact_email": "contact@example.com",
        "seller_contact_phone": "031234567",
        "seller_bank_account_code": "12",
        "seller_bank_account_branch": "123",
        "seller_bank_account_number": "123456",
        "seller_bank_routing_number_foreign": null,
        "seller_bank_account_number_foreign": null,
        "seller_need_foreign_currency": null,
        "seller_was_rejected_by_bank": null,
        "seller_bank_rejection_reason": null,
        "seller_source_of_finance": null,
        "seller_required_service_type": null,
        "seller_account_type": "Unrestricted"
      },
      "seller_address": {
        "seller_address_city": "Tel Aviv",
        "seller_address_street": "Herzl",
        "seller_address_street_number": "10",
        "seller_address_country": "IL"
      },
      "seller_fees": {
        "fee_market_fee": "1.50",
        "fee_default_processing_fee": "2.50",
        "fee_default_processing_charge": "1.20",
        "fee_default_rapid_settlement_fee": "0.00",
        "fee_default_discount_fee": "0.50",
        "fee_default_premium_processing_fee": "2.50",
        "fee_corporate_processing_fee": "2.50",
        "fee_foreign_processing_fee": "3.50",
        "fee_foreign_processing_charge": "1.20",
        "fee_foreign_rapid_settlement_fee": "0.00",
        "fee_foreign_discount_fee": "0.50",
        "fee_foreign_premium_processing_fee": "3.50",
        "fee_foreign_corporate_processing_fee": "3.50",
        "fee_forcurr_processing_fee": "3.50",
        "fee_forcurr_processing_charge": "0.30",
        "fee_forcurr_rapid_settlement_fee": "0.00",
        "fee_forcurr_discount_fee": "0.50",
        "fee_forcurr_premium_processing_fee": "3.50",
        "fee_forcurr_corporate_processing_fee": "3.50"
      },
      "seller_currencies": [
        "ILS",
        "USD"
      ],
      "seller_processing_percent": 12,
      "seller_processing_limit": 100000,
      "seller_timezone": "Asia/Jerusalem",
      "seller_display_language": "he",
      "seller_wallets": {
        "ILS": {
          "wallet_currency": "ILS",
          "wallet_total": 10000,
          "wallet_releasable": 2500
        },
        "USD": {
          "wallet_currency": "USD",
          "wallet_total": 0,
          "wallet_releasable": 0
        }
      },
      "seller_monthly_invoices": {
        "1234": {
          "invoice_reference": "2026-09",
          "invoice_created": "2026-10-01",
          "invoice_doc_number": "1234",
          "invoice_currency": "ILS",
          "invoice_url": "https://example.com/invoices/1234.pdf",
          "invoice_details_url": "https://example.com/invoice-details/1234"
        }
      },
      "seller_monthly_balance_authorizations": {
        "2026": {
          "9": "https://example.com/balance/2026-09"
        }
      }
    }
  ]
}
```

### 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
}
```