---
api: 'Merchant API'
---

# Update a subscription

Update a subscription's details.

You can update a subscription and specific parameters based on the value of the `state` parameter:

| State parameter value | Modifiable parameters |
| --------------------- | --------------------- |
| `pending`, `active`, `overdue`, `paused` | You can modify all listed parameters. |
| `cancelled`, `finished` | You cannot modify parameters. These are final states. |

**Common use cases:**
- **Update external reference**: When you need to sync with updated customer records in your system, correct an initial reference value, or re-map the subscription to a different internal tracking ID to maintain consistency with your database.

## Endpoint

PATCH `/api/subscriptions/{subscription_id}`

## Request body

### Attributes

- `external_reference` (string, optional)
    Optional external reference for the subscription.
    
    Use this field to store your own system's identifier for easy tracking and correlation.

## Returns

### 200

Subscription updated successfully

#### Response attributes

- `id` (string)
    Unique identifier for the subscription.
- `external_reference` (string, optional)
    Optional external reference for the subscription.
    
    Use this field to store your own system's identifier for easy tracking and correlation.
- `state` (enum)
    The state of the subscription.
    
    | State | Description |
    | ----- | ----------- |
    | `pending` | The subscription has been created but is not yet active. This typically occurs when awaiting the first payment or setup completion. |
    | `active` | The subscription is currently active and billing cycles are processing normally. |
    | `overdue` | The subscription has a failed payment and is awaiting resolution. |
    | `paused` | The subscription has been temporarily paused and no billing will occur. |
    | `cancelled` | The subscription has been cancelled and will not renew. |
    | `finished` | The subscription has completed all billing cycles (for limited-duration subscriptions). |
    Possible enum values:

    - `pending`
    - `active`
    - `overdue`
    - `paused`
    - `cancelled`
    - `finished`
- `customer_id` (string)
    Unique identifier for the customer.
- `plan_id` (string)
    Unique identifier for the subscription plan.
- `plan_variation_id` (string)
    Unique identifier for the subscription plan variation.
- `payment_method_type` (enum)
    The type of payment method used for the subscription.
    
    | Type | Description |
    | ---- | ----------- |
    | `automatic` | Payments are automatically charged to the customer's saved payment method. |
    | `manual` | Payments require manual processing by the customer. |
    Possible enum values:

    - `automatic`
    - `manual`
- `payment_method_id` (string, optional)
    Unique identifier for the payment method.
- `created_at` (string)
    The date and time the subscription was created in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `updated_at` (string)
    The date and time the subscription was last updated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
- `start_date` (string | null, optional)
    The date and time the subscription started in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    
    This field is `null` until the subscription becomes active.
- `current_cycle_id` (string)
    Unique identifier for the subscription cycle.
- `trial_duration` (string, optional)
    The trial period duration for this subscription in [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations) (e.g., "P14D" for 14 days).
    
    ### Override plan defaults
    
    Subscription plans can define a default trial duration. When creating a subscription, you can use this field to override the plan's default trial period:
    
    | Field value | Behaviour | Example |
    | ----------- | -------- | ------- |
    | **Not provided** | Uses the trial duration defined in the plan (if any) | Plan has `"P7D"` → subscription gets 7-day trial |
    | **Different value** | Overrides the plan's default trial duration | Plan has `"P7D"` → set to `"P30D"` for promotional offer, or `"P3D"` to reduce |
    | **`"P0D"`** | Explicitly skips the trial period | Plan has `"P7D"` → set to `"P0D"` to skip trial entirely |
    
    :::note
    Only days (`D`) are allowed. Time components such as hours, minutes, or seconds are not permitted.
    :::
- `trial_end_date` (string | null, optional)
    The date and time when the subscription's trial period ends in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
    
    This value is automatically calculated by the system as: `start_date` + `trial_duration`
    
    The `trial_duration` used in the calculation comes from either:
    - The subscription's custom `trial_duration` (if provided at creation time), or
    - The plan's default `trial_duration` (if no override was specified)
    
    This field is `null` when the subscription has no trial period (e.g., when `trial_duration` is not set or is `"P0D"`).
- `setup_order_id` (string, optional)
    The ID of the order created for handling the setup payment for the subscription.
    
    Use the [Retrieve an order](/docs/api/merchant#retrieve-an-order) endpoint with this ID to get order details, including the `checkout_url` for redirecting customers to the Hosted Payment Page or the `token` for widget integration.
    
    :::note
    The order is created in parallel to the subscription and is used to collect the initial payment and save the customer's payment method for future billing cycles.
    :::
- `scheduled_action` (object, optional)
    A pending scheduled action on the subscription, applied at the end of the current billing cycle.

## Error responses

| HTTP status code | Description |
| --- | --- |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Subscription not found |