Skip to main content

​
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

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKENYes
Content-Typeapplication/jsonYes
Acceptapplication/jsonRecommended

​
Request Body

ParameterTypeRequiredDescription
product_idintegerYesThe subscription product ID
variant_idintegerYesThe subscription variant ID (determines duration and price)
customer.idintegerConditionalExisting customer ID. If provided, other customer fields are ignored.
customer.country_codestringConditionalCustomer’s country dial code (e.g. "966" for Saudi Arabia, "971" for UAE). Required if customer.id is not provided.
customer.phonestringConditionalCustomer’s phone number, 5-15 digits (e.g. "512345678"). Required if customer.id is not provided.
customer.firstNamestringConditionalCustomer’s first name. Required if customer.id is not provided.
customer.lastNamestringConditionalCustomer’s last name. Required if customer.id is not provided.
customer.emailstringConditionalCustomer’s email address. Required if customer.id is not provided.
success_urlstringYesURL to redirect to after successful payment
cancel_urlstringYesURL to redirect to if the customer cancels
metadataobjectNoKey-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_idstringNoYour 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"
  }'

​
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"
  }'

​
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

FieldTypeDescription
session_idstringUnique identifier for the checkout session
checkout_urlstringURL to redirect the customer to for payment
expires_atstringISO 8601 timestamp when the session expires (7 minutes)

​
Flow

  1. Your server creates a checkout session via this endpoint
  2. Redirect the customer to the checkout_url
  3. The customer completes payment on the hosted checkout page
  4. On success, the customer is redirected to your success_url with ?rmz-subscription-id={id} appended as a query parameter
  5. 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

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