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

# Extend Subscription

> Extend a subscription's current period by a specified number of days or months.

# Extend 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}"}/extend</code>
</div>

Extends a subscription's current billing period by a specified number of days or months. This is useful for courtesy extensions, compensation for service outages, or promotional offers. You must provide either `days` or `months` (but not both).

<Warning>
  This endpoint has an idempotency guard. If a duplicate request is made within 10 seconds, it will return `429 Too Many Requests` instead of double-extending the subscription.
</Warning>

<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                                                                           |
| --------- | ------- | ------------------------- | ------------------------------------------------------------------------------------- |
| `days`    | integer | Required without `months` | Number of days to extend the subscription (1-365)                                     |
| `months`  | integer | Required without `days`   | Number of months to extend the subscription (1-24). Each month is treated as 30 days. |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://merchant-api.rmz.gg/shawarma/subscriptions/501/extend" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"days": 7}'
  ```

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

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

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

  ```php PHP theme={null}
  $ch = curl_init("https://merchant-api.rmz.gg/shawarma/subscriptions/501/extend");
  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(["days" => 7]));
  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 extension are shown below — see [Get Subscription](./get-subscription) for the complete field list.

```json theme={null}
{
  "message": "Subscription extended successfully",
  "data": {
    "id": 501,
    "status": "active",
    "external_customer_id": "usr_abc123",
    "current_period_start": "2025-06-01T00:00:00.000000Z",
    "current_period_end": "2025-07-08T00:00:00.000000Z",
    "end_date": "2025-07-08T00:00:00.000000Z"
  },
  "api": "rmz.shawarma",
  "timestamp": 1699999999
}
```

## Response Fields

The response is the full `SubscriptionResource`. See [Get Subscription](./get-subscription) for the complete list. The fields most relevant to extension:

| Field                  | Type        | Description                                                                                                                                               |
| ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | integer     | Subscription ID                                                                                                                                           |
| `status`               | string      | Current subscription status                                                                                                                               |
| `external_customer_id` | string/null | Stable identifier the merchant supplied at checkout creation. Use this to correlate RMZ subscriptions with your own user records. `null` if not supplied. |
| `current_period_start` | string      | Start of the current billing period                                                                                                                       |
| `current_period_end`   | string      | New end of the current billing period (extended)                                                                                                          |
| `end_date`             | string      | Updated subscription end date                                                                                                                             |

<Tip>
  A `subscription.updated` webhook event is fired when a subscription is extended, including the number of days added and the new end date.
</Tip>

## Error Responses

| Code  | Description                                                       |
| ----- | ----------------------------------------------------------------- |
| `401` | Unauthorized — invalid or missing token                           |
| `404` | Subscription not found                                            |
| `409` | Subscription is canceled or expired and cannot be extended        |
| `422` | Validation error — must provide `days` (1-365) or `months` (1-24) |