> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rmz.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Subscription

> Cancel a customer subscription immediately or at the end of the current period.

# Cancel Subscription

<div className="flex items-center gap-2 mb-4">
  <span className="px-2 py-1 bg-blue-100 text-blue-800 rounded text-sm font-mono font-bold">POST</span>
  <code>/subscriptions/{"{id}"}/cancel</code>
</div>

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).

<Snippet file="rmz-plus-required.mdx" />

## Authentication

<Snippet file="auth-bearer-header.mdx" />

## Headers

| 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

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://merchant-api.rmz.gg/shawarma/subscriptions/501/cancel",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer YOUR_API_TOKEN",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ effective: "end_of_period" })
    }
  );
  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://merchant-api.rmz.gg/shawarma/subscriptions/501/cancel",
      headers={
          "Authorization": "Bearer YOUR_API_TOKEN",
          "Content-Type": "application/json"
      },
      json={"effective": "end_of_period"}
  )
  result = response.json()
  ```

  ```php PHP theme={null}
  $ch = curl_init("https://merchant-api.rmz.gg/shawarma/subscriptions/501/cancel");
  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(["effective" => "end_of_period"]));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $response = json_decode(curl_exec($ch), true);
  ```
</CodeGroup>

## Success Response

Returns the full subscription object in the standard `SubscriptionResource` shape — identical to [Get Subscription](./get-subscription), [List Subscriptions](./list-subscriptions), and [Lookup Subscriptions](./lookup-subscriptions). The fields most relevant to cancellation are shown below — see [Get Subscription](./get-subscription) for the complete field list.

```json theme={null}
{
  "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`.                                     |

<Note>
  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.
</Note>

<Warning>
  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.
</Warning>

## 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 |