Create Checkout Session

POST/subscriptions/checkout-sessions

Creates a hosted checkout session that redirects the customer to complete their subscription purchase. This is the primary way for SaaS integrations to create subscriptions programmatically.

Authentication

Headers

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

Request Body

Parameter	Type	Required	Description
`product_id`	integer	Yes	The subscription product ID
`variant_id`	integer	Yes	The subscription variant ID (determines duration and price)
`customer.id`	integer	Conditional	Existing customer ID. If provided, other customer fields are ignored.
`customer.country_code`	string	Conditional	Customer’s country dial code (e.g. `"966"` for Saudi Arabia, `"971"` for UAE). Required if `customer.id` is not provided.
`customer.phone`	string	Conditional	Customer’s phone number, 5-15 digits (e.g. `"512345678"`). Required if `customer.id` is not provided.
`customer.firstName`	string	Conditional	Customer’s first name. Required if `customer.id` is not provided.
`customer.lastName`	string	Conditional	Customer’s last name. Required if `customer.id` is not provided.
`customer.email`	string	Conditional	Customer’s email address. Required if `customer.id` is not provided.
`success_url`	string	Yes	URL to redirect to after successful payment
`cancel_url`	string	Yes	URL to redirect to if the customer cancels
`metadata`	object	No	Key-value pairs to attach to the subscription. Max 20 keys, values max 500 characters. Included in all webhook payloads and API responses. Use this for any additional per-subscription custom data you want echoed back.
`external_customer_id`	string	No	Your system’s stable user identifier (max 191 characters). Use this as the correlation key between RMZ subscriptions and your own user records. It is included in every subscription webhook payload at `data.subscription.external_customer_id` and in every subscription API response at `data.external_customer_id` (get, list, lookup, cancel, pause, unpause, extend). Can also be used as a query parameter on the `/subscriptions/lookup` endpoint.

You must provide either customer.id (to reference an existing customer) or the full set of customer.country_code, customer.phone, customer.firstName, customer.lastName, and customer.email (to create or match a customer).

Example Request (New Customer)

curl -X POST "https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 102,
    "variant_id": 15,
    "customer": {
      "country_code": "966",
      "phone": "512345678",
      "firstName": "Ahmed",
      "lastName": "Ali",
      "email": "ahmed@example.com"
    },
    "metadata": {
      "external_user_id": "usr_abc123",
      "plan": "pro"
    },
    "success_url": "https://yourapp.com/subscription/success",
    "cancel_url": "https://yourapp.com/subscription/cancel"
  }'

const response = await fetch(
  "https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      product_id: 102,
      variant_id: 15,
      customer: {
        country_code: "966",
        phone: "512345678",
        firstName: "Ahmed",
        lastName: "Ali",
        email: "ahmed@example.com"
      },
      success_url: "https://yourapp.com/subscription/success",
      cancel_url: "https://yourapp.com/subscription/cancel"
    })
  }
);
const session = await response.json();

import requests

response = requests.post(
    "https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "product_id": 102,
        "variant_id": 15,
        "customer": {
            "country_code": "966",
            "phone": "512345678",
            "firstName": "Ahmed",
            "lastName": "Ali",
            "email": "ahmed@example.com"
        },
        "success_url": "https://yourapp.com/subscription/success",
        "cancel_url": "https://yourapp.com/subscription/cancel"
    }
)
session = response.json()

$ch = curl_init("https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_TOKEN",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "product_id" => 102,
    "variant_id" => 15,
    "customer" => [
        "country_code" => "966",
        "phone" => "512345678",
        "firstName" => "Ahmed",
        "email" => "ahmed@example.com"
    ],
    "success_url" => "https://yourapp.com/subscription/success",
    "cancel_url" => "https://yourapp.com/subscription/cancel"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

Example Request (Existing Customer)

curl -X POST "https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 102,
    "variant_id": 15,
    "customer": {
      "id": 4501
    },
    "success_url": "https://yourapp.com/subscription/success",
    "cancel_url": "https://yourapp.com/subscription/cancel"
  }'

const response = await fetch(
  "https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      product_id: 102,
      variant_id: 15,
      customer: { id: 4501 },
      success_url: "https://yourapp.com/subscription/success",
      cancel_url: "https://yourapp.com/subscription/cancel"
    })
  }
);
const session = await response.json();

import requests

response = requests.post(
    "https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions",
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json"
    },
    json={
        "product_id": 102,
        "variant_id": 15,
        "customer": {"id": 4501},
        "success_url": "https://yourapp.com/subscription/success",
        "cancel_url": "https://yourapp.com/subscription/cancel"
    }
)
session = response.json()

$ch = curl_init("https://merchant-api.rmz.gg/shawarma/subscriptions/checkout-sessions");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer YOUR_API_TOKEN",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    "product_id" => 102,
    "variant_id" => 15,
    "customer" => ["id" => 4501],
    "success_url" => "https://yourapp.com/subscription/success",
    "cancel_url" => "https://yourapp.com/subscription/cancel"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);

Success Response

{
  "message": null,
  "data": {
    "session_id": "cs_abc123def456",
    "checkout_url": "https://billing.rmz.gg/checkout/01KNAE1283PNWZDNE5W2TNRY5J",
    "expires_at": "2025-06-01T01:00:00.000000Z"
  },
  "api": "rmz.shawarma",
  "timestamp": 1699999999
}

Response Fields

Field	Type	Description
`session_id`	string	Unique identifier for the checkout session
`checkout_url`	string	URL to redirect the customer to for payment
`expires_at`	string	ISO 8601 timestamp when the session expires (7 minutes)

Flow

Your server creates a checkout session via this endpoint
Redirect the customer to the checkout_url
The customer completes payment on the hosted checkout page
On success, the customer is redirected to your success_url with ?rmz-subscription-id={id} appended as a query parameter
A subscription.created webhook is fired to your webhook endpoint

Example redirect:

https://yourapp.com/subscription/success?rmz-subscription-id=501

Use the rmz-subscription-id query parameter from the redirect to immediately look up the subscription. Always also listen for the subscription.created webhook to confirm the subscription was successfully created, as the redirect alone is not a guarantee of payment success.

Error Responses

Code	Description
`401`	Unauthorized — invalid or missing token
`404`	Product or variant not found
`422`	Validation error — missing or invalid parameters

Overview

Store

Orders

Products

Categories

Subscriptions

Portal Sessions

Create Checkout Session

Create Checkout Session

Authentication

Headers

Request Body

Example Request (New Customer)

Example Request (Existing Customer)

Success Response

Response Fields

Flow

Error Responses

​Create Checkout Session

​Authentication

​Headers

​Request Body

​Example Request (New Customer)

​Example Request (Existing Customer)

​Success Response

​Response Fields

​Flow

​Error Responses

Create Checkout Session

Authentication

Headers

Request Body

Example Request (New Customer)

Example Request (Existing Customer)

Success Response

Response Fields

Flow

Error Responses