---
title: "Update Subscription"
method: PATCH
path: "/v1/subscriptions/{id}"
tags: ["subscriptions", "public"]
---

# Update Subscription

`PATCH /v1/subscriptions/{id}`

Update a subscription.

**Scopes**: `subscriptions:write`

## Path parameters

- `id` string, uuid4, required — The subscription ID.

## Request body

- union
  - SubscriptionUpdateBase
    - `metadata` object — Key-value object allowing you to store additional information. The key must be a string with a maximum length of **40 characters**. The value must be either: * A string with a maximum length of **500 characters** * An integer * A floating-point number * A boolean You can store up to **50 key-value pairs**.
    - `product_id` string, uuid4, nullable — Update subscription to another product.
    - `proration_behavior` 'invoice' | 'prorate' | 'next_period' | 'reset'
    - `discount_id` string, uuid4, nullable — Update the subscription to apply a new discount. If set to `null`, the discount will be removed. The change will be applied on the next billing cycle.
    - `trial_end` union — Set or extend the trial period of the subscription. If set to `now`, the trial will end immediately.
      - string, date-time
      - 'now'
  - SubscriptionUpdateSeats
    - `seats` integer, required — Update the number of seats for this subscription.
    - `proration_behavior` 'invoice' | 'prorate' | 'next_period' | 'reset'
  - SubscriptionUpdateBillingPeriod
    - `current_billing_period_end` string, date-time, required — Set a new date for the end of the current billing period. The subscription will renew on this date. The new date can be earlier or later than the current period end, as long as it's in the future. It is not possible to update the current billing period on a canceled subscription.
  - SubscriptionCancel
    - `customer_cancellation_reason` 'customer_service' | 'low_quality' | 'missing_features' | 'switched_service' | 'too_complex' | 'too_expensive' | 'unused' | 'other'
    - `customer_cancellation_comment` string, nullable — Customer feedback and why they decided to cancel. **IMPORTANT:** Do not use this to store internal notes! It's intended to be input from the customer and is therefore also available in their Polar purchases library. Only set this in case your own service is requesting the reason from the customer. Or you copy a message directly from a customer conversation, i.e support.
    - `cancel_at_period_end` boolean, required — Cancel an active subscription once the current period ends. Or uncancel a subscription currently set to be revoked at period end.
  - SubscriptionRevoke
    - `customer_cancellation_reason` 'customer_service' | 'low_quality' | 'missing_features' | 'switched_service' | 'too_complex' | 'too_expensive' | 'unused' | 'other'
    - `customer_cancellation_comment` string, nullable — Customer feedback and why they decided to cancel. **IMPORTANT:** Do not use this to store internal notes! It's intended to be input from the customer and is therefore also available in their Polar purchases library. Only set this in case your own service is requesting the reason from the customer. Or you copy a message directly from a customer conversation, i.e support.
    - `revoke` true, required — Cancel and revoke an active subscription immediately
  - SubscriptionPause
    - `pause_at_period_end` boolean, required — Pause an active subscription at the end of the current period. Or cancel a scheduled pause on a subscription set to be paused at period end.
    - `resumes_at` string, date-time, nullable — Date at which the paused subscription should automatically resume. If not set, the subscription stays paused until it is resumed manually. Must be after the current period end.
  - SubscriptionResume
    - `resume` true, required — Resume a paused subscription immediately, starting a new billing period and charging the customer.
  - SubscriptionUpdateClear
    - `pending_update` unknown, required

## Response `200`

Subscription updated.

- Subscription — unresolved $ref

## Other responses

- `402` — Payment required to apply the subscription update.
- `403` — Subscription is already canceled or will be at the end of the period, or is not active.
- `404` — Subscription not found.
- `409` — Subscription is pending an update.
- `422` — Validation Error

---

[API](https://skmtc.net/polar/apis/polar-api.md) · [All operations](https://skmtc.net/polar/apis/polar-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polar/polar-api/revisions/77e4ef94fcc3/schema)