# List subscriptions

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

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

## 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 subscriptions for one seller or all your sellers, with their status, schedule and buyer. Use `sub_status` to find active (`2`) or failing (`4`, `7`) subscriptions. The response never contains the `buyer_key`. See [Recurring Payments](/payments/saved-cards-recurring) for how subscriptions are charged and retried.

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.

Status values are numbers, see [Subscription Statuses](/payments/codes-statuses/subscription-statuses). Iteration types are on [Subscription Iteration Types](/payments/codes-statuses/subscription-iteration-types). Without `sub_type`, all four subscription types are returned.

Filters are exact matches, except `sub_created_min` / `sub_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 and the `*_min` / `*_max` filters are Asia/Jerusalem local time, not UTC. 

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. |
| `sub_payme_code` | integer | no | PayMe's numeric subscription code. |
| `sub_payme_id` | string | no | PayMe's subscription ID. |
| `subscription_id` | string | no | Your own reference set on generate-subscription. Not unique: several subscriptions can match. |
| `sub_parent_code` | integer | no | Code of the parent the subscription was created from, such as its template. |
| `sub_type` | integer | no | Subscription type, or an array of them: `1` regular, `2` created from a template, `10` template, `20` payment contract. Default: all four. |
| `sub_created` | string | no | Exact creation date and time, `yyyy-mm-dd hh:mm:ss`. |
| `sub_created_min` | string | no | Created at or after this time, `yyyy-mm-dd hh:mm:ss`. |
| `sub_created_max` | string | no | Created at or before this time, `yyyy-mm-dd hh:mm:ss`. |
| `sub_status` | integer | no | Subscription status, or an array of them: `1` initial, `2` active, `3` paused, `4` failed, `5` canceled, `6` completed, `7` failed, pending an automatic retry. See [Subscription Statuses](/payments/codes-statuses/subscription-statuses). |
| `sub_iteration_type` | integer | no | Iteration type, see [Subscription Iteration Types](/payments/codes-statuses/subscription-iteration-types). |
| `sub_price` | integer | no | Exact price, in minor units (`5075` = 50.75). |
| `sub_currency` | string | no | Subscription currency, 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code. |
| `sub_iterations` | integer | no | Total number of charges. `-1` for a subscription with no end. |
| `sub_paid` | boolean | no | `true` returns only subscriptions the buyer has paid (a payment method is saved), `false` only unpaid ones. |
| `sub_send_notification` | boolean | no | `true` returns only `initial` subscriptions 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. |
| `buyer_name` | string | no | Buyer's full name. |
| `buyer_email` | string | no | Buyer's email. |
| `buyer_phone` | string | no | Buyer's phone number. |
| `buyer_social_id` | string | no | Buyer's national ID number. |
| `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 `sub_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",
  "sub_status": [
    4,
    7
  ]
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/get-subscriptions' \
  -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",
  "sub_status": [
    4,
    7
  ]
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/get-subscriptions", {
  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",
    "sub_status": [
      4,
      7
    ]
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/get-subscriptions",
    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",
        "sub_status": [
            4,
            7,
        ],
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_status": [
    4,
    7
  ]
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/get-subscriptions');
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 subscriptions. |
| `items[].seller_payme_id` | string | The seller's MPL. |
| `items[].seller_id` | string | Your own ID for the seller, or `null`. |
| `items[].sub_payme_id` | string | PayMe's subscription ID. |
| `items[].sub_payme_code` | integer | PayMe's numeric subscription code. |
| `items[].sub_parent_code` | integer | Code of the parent the subscription was created from, or `null`. |
| `items[].subscription_id` | string | Your own reference, as sent to generate-subscription. |
| `items[].sub_type` | integer | Subscription type: `1` regular, `2` created from a template, `10` template, `20` payment contract. |
| `items[].sub_created` | string | Creation time, `yyyy-mm-dd hh:mm:ss`. |
| `items[].sub_start_date` | string | Start date of the subscription, `yyyy-mm-dd hh:mm:ss`. |
| `items[].sub_prev_date` | string | Date of the previous charge, `yyyy-mm-dd hh:mm:ss`, or `null`. |
| `items[].sub_next_date` | string | Date of the next charge, `yyyy-mm-dd hh:mm:ss`, or `null`. |
| `items[].sub_status` | integer | Subscription status: `1` initial, `2` active, `3` paused, `4` failed, `5` canceled, `6` completed, `7` failed, pending an automatic retry. See [Subscription Statuses](/payments/codes-statuses/subscription-statuses). |
| `items[].sub_iteration_type` | integer | Iteration type, see [Subscription Iteration Types](/payments/codes-statuses/subscription-iteration-types). |
| `items[].sub_currency` | string | Subscription currency, 3-letter ISO 4217 code. |
| `items[].sub_price` | integer | Price of each charge, in minor units (`5075` = 50.75). |
| `items[].sub_description` | string | Description of the subscription. |
| `items[].sub_iterations` | integer | Total number of charges. `-1` when the subscription has no end. |
| `items[].sub_iterations_completed` | integer | Charges completed so far. |
| `items[].sub_iterations_skipped` | integer | Charges skipped. |
| `items[].sub_iterations_left` | integer | Charges left. |
| `items[].sub_payment_date` | string | When the buyer's payment method was saved (the first successful payment), `yyyy-mm-dd hh:mm:ss`, or `null`. |
| `items[].sub_error_text` | string | Reason for the last failure, if any. |
| `items[].sub_url` | string | Link to the subscription's payment page. |
| `items[].sub_paid` | boolean | `true` once the buyer has paid and a payment method is saved. |
| `items[].sub_buyer_details` | object | The buyer. |
| `items[].sub_buyer_details.buyer_card_mask` | string | Masked card number: first 6 and last 4 digits. |
| `items[].sub_buyer_details.buyer_name` | string | Buyer's full name. |
| `items[].sub_buyer_details.buyer_email` | string | Buyer's email. |
| `items[].sub_buyer_details.buyer_phone` | string | Buyer's phone number. |
| `items[].sub_buyer_details.buyer_social_id` | string | Buyer's national ID number. |

```json
{
  "status_code": 0,
  "items_count": 1,
  "items": [
    {
      "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
      "seller_id": "store-1001",
      "sub_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
      "sub_payme_code": 1234,
      "sub_parent_code": null,
      "subscription_id": "member-778",
      "sub_type": 1,
      "sub_created": "2026-01-01 15:15:15",
      "sub_start_date": "2026-01-10 08:00:00",
      "sub_prev_date": "2026-10-10 08:00:00",
      "sub_next_date": "2026-11-10 08:00:00",
      "sub_status": 7,
      "sub_iteration_type": 3,
      "sub_currency": "ILS",
      "sub_price": 10000,
      "sub_description": "Monthly membership",
      "sub_iterations": 12,
      "sub_iterations_completed": 9,
      "sub_iterations_skipped": 0,
      "sub_iterations_left": 3,
      "sub_payment_date": "2026-01-10 08:00:05",
      "sub_error_text": "Card declined",
      "sub_url": "https://sandbox.payme.io/subscription/generate/XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
      "sub_paid": true,
      "sub_buyer_details": {
        "buyer_card_mask": "458045******4580",
        "buyer_name": "Israel Israeli",
        "buyer_email": "buyer@example.com",
        "buyer_phone": "0500000001",
        "buyer_social_id": "000000018"
      }
    }
  ]
}
```

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