List Subscriptions

Retrieve a paginated list of customer subscriptions with optional filters.

List Subscriptions

GET/subscriptions

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

Authentication

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

cURL

curl -X GET "https://merchant-api.rmz.gg/shawarma/subscriptions?customerEmail=[e-mail]" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Success Response

{
  "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

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

All Subscriptions (No Filter)

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