# List Subscriptions

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

## Credentials

- Request body field `payme_client_key` (required): PayMe Partner Key

## Overview

You can retreive data on subscriptions processed by your sellers using this endpoint. 

To understand the different use-cases for this API, See Get Subscriptions API guide [here](https://docs.paymeservice.com/docs/payme-public/b3A6MjU2MDk2MjE-get-sales). 


#### Subscription Iteration Types
You can find them in the following guide - [Subscription Iteration Types](/guides-and-use-cases-migrated/lists-statuses/subscription-iteration-types).

#### Subscription Statuses
You can find them in the following guide - [Subscription Statuses](/guides-and-use-cases-migrated/lists-statuses/subscription-statuses).

#### Query pagination (more than 500 results)

If you are sending a query and expect to receive more than 500 results, make sure you use this function of Query Pagination. 

```json
{
  "seller_payme_id": "MPL1DEMO-XXXXXXXX-XXXXXXXX-XXXXXXXX",
  ...
  "page_size": 100, // Max allowed page size is 500
  "page": 1
}
```

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | PayMe Partner Key |
| `seller_payme_id` | string | no | Our unique seller ID (MPL). If you are a partner, you can use multiple seller_payme_id attributes to retreive data for these specific sellers |
| `seller_id` | string | no | Merchant's unique seller ID for correlation with us |
| `sub_payme_code` | string | no | Our unique subscription code |
| `sub_payme_id` | string | no | Our unique sub ID |
| `sub_created` | string | no | Exact creation date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_created_min` | string | no | Earliest creation date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_created_max` | string | no | Latest date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_status` | string | no | Subscription status. You can find them in the following guide - [Subscription Statuses](/guides-and-use-cases-migrated/lists-statuses/subscription-statuses). |
| `sub_iteration_type` | number | no | Subscription type ID. You can find them in the following guide - [Subscription Iteration Types](/guides-and-use-cases-migrated/lists-statuses/subscription-iteration-types). |
| `sub_price` | number | no | Subscription final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `sub_currency` | string | no | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `sub_iterations` | number | no | Subscription amount of iterations |
| `sub_start_date` | string | no | Exact start date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `sub_paid` | boolean | no | Was the subscription paid or not |

### Request example

```json
{
  "payme_client_key": "XXXXXXXX",
  "sub_payme_code": "1234"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/get-subscriptions' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "payme_client_key": "XXXXXXXX",
  "sub_payme_code": "1234"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/get-subscriptions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "payme_client_key": "XXXXXXXX",
    "sub_payme_code": "1234"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/get-subscriptions",
    json={
        "payme_client_key": "XXXXXXXX",
        "sub_payme_code": "1234",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "payme_client_key": "XXXXXXXX",
  "sub_payme_code": "1234"
}
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',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;
```

## Responses

### 200 — OK (success)

| Field | Type | Description |
| --- | --- | --- |
| `items_count` | number | Number of subscription |
| `items` | array |  |
| `items[].seller_payme_id` | string | Our unique seller ID |
| `items[].seller_id` | string | Merchant's unique seller ID for correlation with us |
| `items[].sub_payme_id` | string | Our unique sub ID |
| `items[].payme_sub_code` | number | Our unique subscription code |
| `items[].sub_created` | string | Exact creation date and time for which to retrieve subscriptions. ISO-8601 formatted |
| `items[].sub_start_date` | string | Exact state date and time for which the subscription will be initiated |
| `items[].sub_status` | string | Subscription status (for more info about the statuses, see table below) |
| `items[].sub_iteration_type` | number | Subscription type ID (for more info about the types, see table [Subscription Iteration Types](/guides-and-use-cases-migrated/lists-statuses/subscription-iteration-types)) |
| `items[].sub_price` | number | Subscription final price. For example, if the price is 50.75 (max 2 decimal points) the value that needs to be sent is 5075 |
| `items[].sub_description` | string | Brief description about the subscription |
| `items[].sub_iterations` | string | Subscription amount of iterations |
| `items[].sub_iterations_completed` | string | Number of iterations completed |
| `items[].sub_iterations_left` | string | Number of iterations left for the subscription |
| `items[].sub_payment_date` | string | The date the payment is completed for each iteration |
| `items[].sub_error_text` | string | If an error occured, it'll be mentioned in this parameter |
| `items[].sub_currency` | string | Currency of subscription |
| `items[].sub_paid` | boolean | Was the subscription paid |
| `items[].sub_buyer_details` | object |  |
| `items[].sub_buyer_details.buyer_card_mask` | string | The first 6 and last 4 digits of the used card for the subscription |
| `items[].sub_buyer_details.buyer_name` | string | Buyer's first and last 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 social ID number |
| `status_code` | number | Status of the request (0 - success, 1 - error) |

```json
{
  "items_count": 1,
  "items": [
    {
      "seller_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
      "seller_id": "12345",
      "sub_payme_id": "XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX",
      "sub_payme_code": "1234",
      "sub_created": "2016-01-01 15:15:15",
      "sub_start_date": "2016-01-10 08:00:00",
      "sub_prev_date": null,
      "sub_next_date": null,
      "sub_status": "2",
      "sub_iteration_type": "3",
      "sub_price": "10000",
      "sub_description": "Monthly Test Subscription",
      "sub_iterations": "4",
      "sub_iterations_completed": "0",
      "sub_iterations_left": "4",
      "sub_payment_date": "2016-01-02 10:10:10",
      "sub_error_text": "",
      "sub_currency": "USD",
      "sub_paid": true,
      "sub_buyer_details": {
        "buyer_card_mask": "458045******4580",
        "buyer_name": "First Last",
        "buyer_email": "buyer@example.com",
        "buyer_phone": "0540000000",
        "buyer_social_id": "000000001"
      }
    }
  ],
  "status_code": 0
}
```