Create Portal Session
POST/portal-sessions
Creates a billing portal session for a customer. The portal allows customers to view their subscriptions, update payment methods, cancel subscriptions, and change plans — all without requiring you to build a subscription management UI.
Authentication
| Header | Value | Required |
|---|
Authorization | Bearer YOUR_API_TOKEN | Yes |
Content-Type | application/json | Yes |
Accept | application/json | Recommended |
Request Body
| Parameter | Type | Required | Description |
|---|
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. |
return_url | string | No | URL to redirect to when the customer exits the portal |
expires_in | integer | No | Session lifetime in seconds (300-86400, default: 3600) |
You must provide either customer.id (to reference an existing customer) or customer.country_code + customer.phone (to look up the customer by phone).
Example Request (By Phone)
curl -X POST "https://merchant-api.rmz.gg/shawarma/portal-sessions" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"country_code": "966",
"phone": "512345678"
},
"return_url": "https://yourapp.com/account"
}'
Example Request (By Customer ID)
curl -X POST "https://merchant-api.rmz.gg/shawarma/portal-sessions" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customer": {
"id": 4501
},
"return_url": "https://yourapp.com/account"
}'
Success Response
{
"message": "Portal session created successfully",
"data": {
"url": "https://billing.rmz.gg/s/aB3xK9mP...",
"expires_at": "2025-06-01T01:00:00.000000Z"
},
"api": "rmz.shawarma",
"timestamp": 1699999999
}
Response Fields
| Field | Type | Description |
|---|
url | string | URL to redirect the customer to (https://billing.rmz.gg/s/{token}) |
expires_at | string | ISO 8601 timestamp when the session expires (default: 1 hour, configurable via expires_in) |
Portal Capabilities
The customer billing portal allows customers to:
| Capability | Description |
|---|
| View subscriptions | See all active, past due, and canceled subscriptions |
| Cancel subscription | Cancel at end of period or immediately |
| Change plan | Upgrade or downgrade to a different subscription variant |
| Update payment method | Add or change the saved card for auto-renewal |
| View invoices | See payment history and invoice details |
Authentication Flow
The portal uses OTP (one-time password) verification to authenticate the customer:
- Your server creates a portal session via this endpoint
- Redirect the customer to the
url
- The customer verifies their identity via OTP sent to their phone
- After verification, the customer can manage their subscriptions
- When done, the customer is redirected to your
return_url
Portal session URLs are single-use and expire based on the expires_in parameter (default: 1 hour). Generate a new session each time the customer needs to access the portal.
The portal is fully hosted by RMZ and styled to match your store theme. You do not need to build any subscription management UI on your end.
Error Responses
| Code | Description |
|---|
401 | Unauthorized — invalid or missing token |
404 | Customer not found |
422 | Validation error — missing or invalid parameters |
