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

# Managing subscriptions

> Everything you can do to a subscription after it's been created.

Once a subscription exists, you'll want to adjust it over time — change plans, extend trials, tweak seats, or end it. This page covers everything a merchant can do to a subscription, both from the dashboard and through the API.

All of these actions are available under **Sales → Subscriptions** in the dashboard, and via the [Update Subscription](/api-reference/subscriptions/update) endpoint. Customers can also perform a subset of them from the [Customer Portal](/features/customer-portal/introduction) — which ones is controlled by your [portal settings](/features/customer-portal/settings).

## Change the plan

Switch a subscription to a different recurring product — the standard upgrade or downgrade flow.

* When the change takes effect depends on the [proration behavior](/features/subscriptions/proration): `invoice` and `prorate` apply the new product immediately, while `next_period` schedules a pending update that's only applied at the start of the next billing cycle.
* The new product must share the subscription's currency and must either both be seat-based or both not be — you can't switch a flat subscription to a seat-based product or vice versa.
* You can't change the plan on a **trialing** subscription or on one that's already canceled or scheduled to cancel. End the trial or uncancel first.
* Custom-priced products (pay-what-you-want) aren't valid destinations for a plan change.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
    --header 'Authorization: Bearer <TOKEN>' \
    --header 'Content-Type: application/json' \
    --data '{
      "product_id": "<new_product_id>",
      "proration_behavior": "prorate"
    }'
  ```

  ```py Python theme={null}
  polar.subscriptions.update(
      id="<subscription_id>",
      subscription_update={
          "product_id": "<new_product_id>",
          "proration_behavior": "prorate",
      },
  )
  ```
</CodeGroup>

Read more in [Proration](/features/subscriptions/proration).

## Change the number of seats

For [seat-based subscriptions](/features/seat-based-pricing), update how many seats the customer is paying for. Like plan changes, when the seat count actually takes effect depends on the [proration behavior](/features/subscriptions/proration): immediate with `invoice` or `prorate`, scheduled for the next cycle with `next_period`.

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "seats": 25, "proration_behavior": "invoice" }'
```

## Apply or change a discount

Attach a [discount](/features/discounts) to an active subscription, or remove the current one by passing `null`. The change is applied to the **next** billing cycle — it doesn't retroactively re-bill the current period.

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "discount_id": "<discount_id>" }'
```

## Manage the trial

You can add, extend, or end a [trial](/features/subscriptions/trials) on any subscription:

* **Add or extend** a trial by setting `trial_end` to a future date. If the subscription is currently active, its status switches to `trialing` and the next charge is postponed to the new date.
* **End a trial immediately** by setting `trial_end` to `"now"`. The subscription becomes `active` and a new billing cycle — and charge — starts on the spot.

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "trial_end": "2026-06-01T00:00:00Z" }'
```

## Reschedule the next renewal

If you need to move a subscription's renewal date — for example, to align several subscriptions on the same day, or to extend the current period as a goodwill gesture — you can set a new `current_billing_period_end`. The new date has to be in the future, and this operation isn't available on canceled subscriptions.

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "current_billing_period_end": "2026-07-15T00:00:00Z" }'
```

## Cancel or revoke

Polar distinguishes between **canceling** and **revoking** a subscription. Both end the customer's access eventually — the difference is when.

### Cancel at period end

Calling cancel (or toggling "Cancel at period end" in the dashboard) sets `cancel_at_period_end = true` and schedules the subscription to end on its `current_period_end`. Until then:

* The subscription stays **active** and the customer keeps their benefits — they paid for that period.
* No further orders are generated after the current one.
* You can **uncancel** at any time before the end date, which reverts the scheduled cancellation.

This is the gentler option and the one customers trigger themselves from the [Customer Portal](/features/customer-portal/introduction). It's also what satisfies the "cancel the way you signed up" requirement in jurisdictions like California's [Automatic Renewal Law](https://oag.ca.gov/consumers/auto-renewing-subscriptions).

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "cancel_at_period_end": true,
    "customer_cancellation_reason": "too_expensive"
  }'
```

You can optionally record a **cancellation reason** and **comment** — useful for tracking churn. The supported reasons are `too_expensive`, `missing_features`, `switched_service`, `unused`, `customer_service`, `low_quality`, `too_complex`, and `other`.

<Note>
  Only set the cancellation reason and comment when they actually come from
  the customer (for example, from a cancellation survey or a support
  conversation). Customers can see their `customer_cancellation_comment` in
  their purchase history, so don't put internal notes there.
</Note>

### Revoke immediately

Revoking ends the subscription **right now**: status moves to `canceled`, `ended_at` is set to the current time, and all benefits are revoked. There's no refund — if you need to issue one, do it separately from [Refunds](/features/refunds).

Use this when access needs to stop immediately — a terms-of-service violation, a chargeback, or an explicit customer request.

```bash cURL theme={null}
curl --request DELETE \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>'
```

<Warning>
  Revoking is irreversible. If you want the option to reverse the decision,
  cancel at period end instead.
</Warning>

### Uncancel

If a subscription is set to cancel at period end and hasn't ended yet, you (or the customer) can reverse the decision. The `cancel_at_period_end` flag is cleared, `ends_at` and `canceled_at` are unset, and the subscription goes back to renewing normally.

```bash cURL theme={null}
curl --request PATCH \
  --url https://api.polar.sh/v1/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{ "cancel_at_period_end": false }'
```

Uncancelling is not possible once the subscription has actually ended.

## What customers can do

The [Customer Portal](/features/customer-portal/introduction) exposes a subset of these actions to the customer, gated by your [portal settings](/features/customer-portal/settings):

* **Cancel at period end** is always available — this is the self-service guarantee the portal provides.
* **Update the default payment method** is always available — the primary way customers recover from a failed renewal.
* **Change plan** is available when **Enable subscription plan changes** is on.
* **Change seats** (for seat-based subscriptions) is available when **Enable subscription seat management** is on.

Everything else on this page is merchant-only: revoking a subscription, applying or changing a discount, extending or ending a trial, and rescheduling the renewal date are not exposed to customers.