## 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](/content/docs/features/subscriptions/proration/index.html): `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. - You can upgrade a non-seat subscription to a seat-based product — the billing customer is auto-promoted to a `team` customer and claims a seat — but you can’t switch a seat-based subscription back to a non-seat product. Non-seat → seat changes must apply immediately, so `next_period` proration isn’t allowed for that transition. - You can’t change the plan on a subscription that’s already canceled or scheduled to cancel — uncancel first. - Plan changes on a **trialing** subscription are allowed. The trial carries over with its end recomputed from the new product’s trial length (anchored to the original `trial_start`). If the new product has no trial — or its trial would already have elapsed — the trial ends immediately and a fresh billing cycle starts on the new product. - Custom-priced products (pay-what-you-want) aren’t valid destinations for a plan change. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "product_id": "", "proration_behavior": "prorate" }' ``` ### Python ```python polar.subscriptions.update( id="", subscription_update={ "product_id": "", "proration_behavior": "prorate", }, ) ``` Read more in [Proration](/content/docs/features/subscriptions/proration/index.html). ## Change the number of seats For [seat-based subscriptions](/content/docs/features/seat-based-pricing/index.html), update how many seats the customer is paying for. Like plan changes, when the seat count actually takes effect depends on the [proration behavior](/content/docs/features/subscriptions/proration/index.html): immediate with `invoice` or `prorate`, scheduled for the next cycle with `next_period`. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "seats": 25, "proration_behavior": "invoice" }' ``` ## Apply or change a discount Attach a [discount](/content/docs/features/discounts/index.html) 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. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "discount_id": "" }' ``` ## Manage the trial You can add, extend, or end a [trial](/content/docs/features/subscriptions/trials/index.html) 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. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --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 revoked subscriptions. If the subscription is scheduled to cancel at period end, its `ends_at` moves with the new date: it ends then instead of on the original period end. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "current_billing_period_end": "2026-07-15T00:00:00Z" }' ``` ## Pause and resume Pausing stops billing without ending the subscription. Use it for seasonal plans or account “freezes”, where a customer steps away for a while and comes back to the same subscription and payment method. ### Pause at period end Calling pause sets `pause_at_period_end = true`. The subscription stays **active** and keeps its benefits until its `current_period_end`, then it moves to the `paused` status: benefits are revoked and no further orders are generated. Pausing never charges the customer and never takes effect mid-period. Pass an optional `resumes_at` date to schedule an automatic resume. It has to be after the current period end. Leave it out to pause indefinitely and resume by hand later. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "pause_at_period_end": true, "resumes_at": "2026-11-01T00:00:00Z" }' ``` You can only pause a subscription that’s active, with no pending cancellation or pause. To cancel a scheduled pause before it takes effect, set `pause_at_period_end` back to `false`. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "pause_at_period_end": false }' ``` ### Resume Resuming a paused subscription takes effect **right now**: status moves back to `active`, a new billing period starts from the resume date, and the customer is charged immediately. The payment method stays on file, so there’s no second checkout. An automatic resume on the `resumes_at` date does exactly the same thing. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "resume": true }' ``` ## 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](/content/docs/features/customer-portal/introduction/index.html). 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). ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --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`. ### 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](/content/docs/features/refunds/index.html). Use this when access needs to stop immediately — a terms-of-service violation, a chargeback, or an explicit customer request. ### cURL ```bash curl --request DELETE \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' ``` Revoking is irreversible. If you want the option to reverse the decision, cancel at period end instead. ### 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. ### cURL ```bash curl --request PATCH \ --url https://api.polar.sh/v1/subscriptions/{subscription_id} \ --header 'Authorization: Bearer ' \ --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](/content/docs/features/customer-portal/introduction/index.html) exposes a subset of these actions to the customer, gated by your [portal settings](/content/docs/features/customer-portal/settings/index.html): - **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. - **Pause and resume** is available when **Enable subscription pause** 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.