Cancel Subscription
POST/subscriptions//cancel
Cancels a customer subscription. You can cancel immediately (access revoked right away) or at the end of the current billing period (customer retains access until the period ends).
Authentication
| Header | Value | Required |
|---|
Authorization | Bearer YOUR_API_TOKEN | Yes |
Content-Type | application/json | Yes |
Accept | application/json | Recommended |
Path Parameters
| Parameter | Type | Required | Description |
|---|
id | integer | Yes | The subscription ID |
Request Body
| Parameter | Type | Required | Description |
|---|
effective | string | No | immediate or end_of_period (default: end_of_period) |
Example Request
curl -X POST "https://merchant-api.rmz.gg/shawarma/subscriptions/501/cancel" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"effective": "end_of_period"}'
Success Response
Returns the full subscription object in the standard SubscriptionResource shape — identical to Get Subscription, List Subscriptions, and Lookup Subscriptions. The fields most relevant to cancellation are shown below — see Get Subscription for the complete field list.
{
"message": "Subscription canceled successfully",
"data": {
"id": 501,
"status": "active",
"external_customer_id": "usr_abc123",
"cancel_at_period_end": true,
"canceled_at": "2025-06-15T12:00:00.000000Z",
"current_period_end": "2025-07-01T00:00:00.000000Z"
},
"api": "rmz.shawarma",
"timestamp": 1699999999
}
Behavior Options
| Behavior | Description |
|---|
end_of_period | The subscription remains active until current_period_end. No renewal will be attempted. This is the default and recommended option. |
immediate | The subscription is canceled and access is revoked immediately. The status changes to canceled. |
When using end_of_period, the subscription status stays active and cancel_at_period_end is set to true. The subscription will transition to expired when the period ends.
Immediate cancellation cannot be undone. The customer would need to create a new subscription. Consider using end_of_period to give the customer the full value of their current billing period.
Error Responses
| Code | Description |
|---|
401 | Unauthorized — invalid or missing token |
404 | Subscription not found |
409 | Subscription is already canceled or expired |
422 | Validation error — invalid effective value, or subscription already canceled/expired |
