List subscriptions

• 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 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. Iteration types are on 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.

Parameters

Request body

Content type: application/json

Every field is optional. Send at least your credentials.

Request example

{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_status": [
    4,
    7
  ]
}

Code samples

curl

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

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

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

$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)

{
  "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. (error)

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