> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rmz.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# List Subscriptions

> Retrieve a paginated list of customer subscriptions with optional filters.

# List Subscriptions

<div className="flex items-center gap-2 mb-4">
  <span className="px-2 py-1 bg-green-100 text-green-800 rounded text-sm font-mono font-bold">GET</span>
  <code>/subscriptions</code>
</div>

Returns a paginated list of customer subscriptions for the authenticated store. You can filter by customer email, phone, or country code.

<Snippet file="rmz-plus-required.mdx" />

## Authentication

<Snippet file="auth-bearer-header.mdx" />

## Headers

| Header          | Value                   | Required    |
| --------------- | ----------------------- | ----------- |
| `Authorization` | `Bearer YOUR_API_TOKEN` | Yes         |
| `Accept`        | `application/json`      | Recommended |

## Query Parameters

| Parameter             | Type    | Required | Description                                   |
| --------------------- | ------- | -------- | --------------------------------------------- |
| `page`                | integer | No       | Page number (default: 1)                      |
| `customerEmail`       | string  | No       | Filter by customer email                      |
| `customerPhone`       | string  | No       | Filter by customer phone number               |
| `customerCountryCode` | string  | No       | Filter by customer country code (e.g., `966`) |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://merchant-api.rmz.gg/shawarma/subscriptions?customerEmail=ahmed@example.com" \
    -H "Authorization: Bearer YOUR_API_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    customerEmail: "ahmed@example.com"
  });

  const response = await fetch(
    `https://merchant-api.rmz.gg/shawarma/subscriptions?${params}`,
    { headers: { "Authorization": "Bearer YOUR_API_TOKEN" } }
  );
  const subscriptions = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://merchant-api.rmz.gg/shawarma/subscriptions",
      headers={"Authorization": "Bearer YOUR_API_TOKEN"},
      params={"customerEmail": "ahmed@example.com"}
  )
  subscriptions = response.json()
  ```

  ```php PHP theme={null}
  $params = http_build_query(["customerEmail" => "ahmed@example.com"]);
  $ch = curl_init("https://merchant-api.rmz.gg/shawarma/subscriptions?{$params}");
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      "Authorization: Bearer YOUR_API_TOKEN"
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = json_decode(curl_exec($ch), true);
  ```
</CodeGroup>

## Success Response

```json theme={null}
{
  "message": null,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 501,
        "status": "active",
        "external_customer_id": "usr_abc123",
        "starts_at": "2026-01-01 00:00:00",
        "ends_at": "2027-01-01 00:00:00",
        "start_date": "2026-01-01 00:00:00",
        "end_date": "2027-01-01 00:00:00",
        "current_period_start": "2026-04-01 00:00:00",
        "current_period_end": "2026-05-01 00:00:00",
        "trial_ends_at": null,
        "cancel_at_period_end": false,
        "canceled_at": null,
        "duration": "monthly",
        "order_id": 78901,
        "auto_renew": true,
        "price": {
          "amount": 99.00,
          "formatted": "99.00 ر.س",
          "currency": "SAR"
        },
        "product": {
          "id": 102,
          "name": "Pro Plan",
          "slug": "pro-plan",
          "type": "subscription"
        },
        "variant": {
          "id": 305,
          "duration": "monthly",
          "duration_text": "شهر",
          "price": 99.00
        },
        "payment_method": {
          "last_four": "4242",
          "scheme": "visa"
        },
        "metadata": null,
        "features": null,
        "is_active": true,
        "is_expired": false,
        "days_remaining": 255,
        "created_at": "2026-01-01T00:00:00.000000Z",
        "updated_at": "2026-04-01T00:00:00.000000Z"
      }
    ],
    "first_page_url": "https://merchant-api.rmz.gg/shawarma/subscriptions?page=1",
    "from": 1,
    "next_page_url": null,
    "path": "https://merchant-api.rmz.gg/shawarma/subscriptions",
    "per_page": 15,
    "prev_page_url": null,
    "to": 1
  },
  "api": "rmz.shawarma",
  "timestamp": 1699999999
}
```

## Duration Values

The `duration` field on each subscription is an enum representing the billing period of the subscription variant. Valid values:

| Value          | Meaning  |
| -------------- | -------- |
| `monthly`      | 1 month  |
| `quarterly`    | 3 months |
| `semiAnnual`   | 6 months |
| `annually`     | 1 year   |
| `biennial`     | 2 years  |
| `quinquennial` | 5 years  |
| `decennial`    | 10 years |

## Status Values

The `status` field reflects the current lifecycle state of the subscription. Possible values:

| Value      | Meaning                                              |
| ---------- | ---------------------------------------------------- |
| `trialing` | In a trial period; access is granted                 |
| `active`   | Fully paid and active; access is granted             |
| `past_due` | Renewal payment failed; may still be in grace period |
| `paused`   | Temporarily paused by the merchant or customer       |
| `canceled` | Canceled; may still have access until period end     |
| `expired`  | Terminal state; access is no longer granted          |

## Filter Examples

### By Customer Phone

```bash theme={null}
curl -X GET "https://merchant-api.rmz.gg/shawarma/subscriptions?customerCountryCode=966&customerPhone=501234567" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

### All Subscriptions (No Filter)

```bash theme={null}
curl -X GET "https://merchant-api.rmz.gg/shawarma/subscriptions?page=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Error Responses

| Code  | Description                             |
| ----- | --------------------------------------- |
| `401` | Unauthorized — invalid or missing token |