List Subscriptions
GET
Returns a paginated list of customer subscriptions for the authenticated store. You can filter by customer email, phone, or country code.
/subscriptionsAuthentication
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 -X GET "https://merchant-api.rmz.gg/shawarma/subscriptions?customerEmail=ahmed@example.com" \
-H "Authorization: Bearer YOUR_API_TOKEN"
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();
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()
$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);
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
Theduration 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
Thestatus 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 |