--- title: "Update Subscription" method: PATCH path: "/v1/customer-portal/subscriptions/{id}" tags: ["customer_portal", "subscriptions", "public"] --- # Update Subscription `PATCH /v1/customer-portal/subscriptions/{id}` Update a subscription of the authenticated customer. ## Path parameters - `id` string, uuid4, required — The subscription ID. ## Request body - union - CustomerSubscriptionUpdateProduct - `product_id` string, uuid4, required — Update subscription to another product. - CustomerSubscriptionUpdateSeats - `seats` integer, required — Update the number of seats for this subscription. - CustomerSubscriptionCancel - `cancel_at_period_end` boolean, nullable — Cancel an active subscription once the current period ends. Or uncancel a subscription currently set to be revoked at period end. - `cancellation_reason` 'customer_service' | 'low_quality' | 'missing_features' | 'switched_service' | 'too_complex' | 'too_expensive' | 'unused' | 'other' - `cancellation_comment` string, nullable — Customer feedback and why they decided to cancel. - CustomerSubscriptionPause - `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, it stays paused until resumed. Must be after the current period end. - CustomerSubscriptionResume - `resume` true, required — Resume a paused subscription immediately, starting a new billing period and charging the customer. - CustomerSubscriptionUpdateClear - `pending_update` unknown, required ## Response `200` Customer subscription updated. - CustomerSubscription - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the object. - `amount` integer, required — The amount of the subscription. - `currency` string, required — The currency of the subscription. - `recurring_interval` 'day' | 'week' | 'month' | 'year', required - `recurring_interval_count` integer, required — Number of interval units of the subscription. If this is set to 1 the charge will happen every interval (e.g. every month), if set to 2 it will be every other month, and so on. - `status` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused', required - `current_period_start` string, date-time, required — The start timestamp of the current billing period. - `current_period_end` string, date-time, required — The end timestamp of the current billing period. - `current_meter_period_start` string, date-time, nullable, required — The start timestamp of the current meter period, if the product has a meter cycle set. Metered credits are granted and overage is settled on this cadence. - `current_meter_period_end` string, date-time, nullable, required — The end timestamp of the current meter period, if the product has a meter cycle set. This is when credits next renew. - `trial_start` string, date-time, nullable, required — The start timestamp of the trial period, if any. - `trial_end` string, date-time, nullable, required — The end timestamp of the trial period, if any. - `cancel_at_period_end` boolean, required — Whether the subscription will be canceled at the end of the current period. - `canceled_at` string, date-time, nullable, required — The timestamp when the subscription was canceled. The subscription might still be active if `cancel_at_period_end` is `true`. - `started_at` string, date-time, nullable, required — The timestamp when the subscription started. - `ends_at` string, date-time, nullable, required — The timestamp when the subscription will end. - `ended_at` string, date-time, nullable, required — The timestamp when the subscription ended. - `past_due_at` string, date-time, nullable — The timestamp when the subscription entered `past_due` status. - `pause_at_period_end` boolean, required — Whether the subscription will be paused at the end of the current period. - `paused_at` string, date-time, nullable, required — The timestamp when the subscription was paused. - `resumes_at` string, date-time, nullable, required — The timestamp when a paused subscription is scheduled to automatically resume, if set. - `customer_id` string, uuid4, required — The ID of the subscribed customer. - `product_id` string, uuid4, required — The ID of the subscribed product. - `discount_id` string, uuid4, nullable, required — The ID of the applied discount, if any. - `checkout_id` string, uuid4, nullable, required - `seats` integer, nullable — The number of seats for seat-based subscriptions. None for non-seat subscriptions. - `customer_cancellation_reason` 'customer_service' | 'low_quality' | 'missing_features' | 'switched_service' | 'too_complex' | 'too_expensive' | 'unused' | 'other', required - `customer_cancellation_comment` string, nullable, required - `product` CustomerSubscriptionProduct, required - `id` string, uuid4, required — The ID of the object. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `trial_interval` 'day' | 'week' | 'month' | 'year', required - `trial_interval_count` integer, nullable, required — The number of interval units for the trial period. - `name` string, required — The name of the product. - `description` string, nullable, required — The description of the product. - `visibility` 'draft' | 'private' | 'public', required - `recurring_interval` 'day' | 'week' | 'month' | 'year', required - `recurring_interval_count` integer, nullable, required — Number of interval units of the subscription. If this is set to 1 the charge will happen every interval (e.g. every month), if set to 2 it will be every other month, and so on. None for one-time products. - `meter_interval` 'day' | 'week' | 'month' | 'year', required - `meter_interval_count` integer, nullable, required — Number of meter interval units. None when no meter cycle is set. - `is_recurring` boolean, required — Whether the product is a subscription. - `is_archived` boolean, required — Whether the product is archived and no longer available. - `organization_id` string, uuid4, required — The ID of the organization owning the product. - `prices` union[], required — List of prices for this product. - union - union - LegacyRecurringProductPriceFixed — A recurring price for a product, i.e. a subscription. **Deprecated**: The recurring interval should be set on the product itself. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'fixed', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `type` 'recurring', required — The type of the price. - `recurring_interval` 'day' | 'week' | 'month' | 'year', required - `price_amount` integer, required — The price in cents. - `legacy` true, required - LegacyRecurringProductPriceCustom — A pay-what-you-want recurring price for a product, i.e. a subscription. **Deprecated**: The recurring interval should be set on the product itself. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'custom', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `type` 'recurring', required — The type of the price. - `recurring_interval` 'day' | 'week' | 'month' | 'year', required - `minimum_amount` integer, required — The minimum amount the customer can pay. If 0, the price is 'free or pay what you want'. - `maximum_amount` integer, nullable, required — The maximum amount the customer can pay. - `preset_amount` integer, nullable, required — The initial amount shown to the customer. - `legacy` true, required - union - ProductPriceFixed — A fixed price for a product. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'fixed', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `price_amount` integer, required — The price in cents. - ProductPriceCustom — A pay-what-you-want price for a product. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'custom', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `minimum_amount` integer, required — The minimum amount the customer can pay. If 0, the price is 'free or pay what you want'. - `maximum_amount` integer, nullable, required — The maximum amount the customer can pay. - `preset_amount` integer, nullable, required — The initial amount shown to the customer. - ProductPriceSeatBased — A seat-based price for a product. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'seat_based', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `seat_tiers` ProductPriceSeatTiersOutput, required — List of pricing tiers for seat-based pricing. The minimum and maximum seat limits are derived from the tiers: - minimum_seats = first tier's min_seats - maximum_seats = last tier's max_seats (None for unlimited) - … - ProductPriceMeteredUnit — A metered, usage-based, price for a product, with a fixed unit price. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'metered_unit', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `unit_amount` string, required — The price per unit in cents. - `cap_amount` integer, nullable, required — The maximum amount in cents that can be charged, regardless of the number of units consumed. - `meter_id` string, uuid4, required — The ID of the meter associated to the price. - `meter` ProductPriceMeter, required — A meter associated to a metered price. - … - `benefits` BenefitPublic[], required — List of benefits granted by the product. - `id` string, uuid4, required — The ID of the benefit. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `type` 'custom' | 'discord' | 'github_repository' | 'downloadables' | 'license_keys' | 'meter_credit' | 'feature_flag' | 'slack_shared_channel', required - `description` string, required — The description of the benefit. - `selectable` boolean, required — Whether the benefit is selectable when creating a product. - `deletable` boolean, required — Whether the benefit is deletable. - `is_deleted` boolean, required — Whether the benefit is deleted. - `organization_id` string, uuid4, required — The ID of the organization owning the benefit. - `medias` ProductMediaFileRead[], required — List of medias associated to the product. - `id` string, uuid4, required — The ID of the object. - `organization_id` string, uuid4, required - `name` string, required - `path` string, required - `mime_type` string, required - `size` integer, required - `storage_version` string, nullable, required - `checksum_etag` string, nullable, required - `checksum_sha256_base64` string, nullable, required - `checksum_sha256_hex` string, nullable, required - `last_modified_at` string, date-time, nullable, required - `version` string, nullable, required - `service` 'product_media', required - `is_uploaded` boolean, required - `created_at` string, date-time, required - `size_readable` string, required - `public_url` string, required - `organization` CustomerOrganization, required - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the object. - `name` string, required — Organization name shown in checkout, customer portal, emails etc. - `slug` string, required — Unique organization slug in checkout, customer portal and credit card statements. - `avatar_url` string, nullable, required — Avatar URL shown in checkout, customer portal, emails etc. - `proration_behavior` 'invoice' | 'prorate' | 'next_period' | 'reset', required - `allow_customer_updates` boolean, required — Whether customers can update their subscriptions from the customer portal. - `customer_portal_settings` OrganizationCustomerPortalSettings, required - `usage` CustomerPortalUsageSettings, required - `show` boolean, required - `subscription` CustomerPortalSubscriptionSettings, required - `update_seats` boolean, required - `update_plan` boolean, required - `pause` boolean - `customer` CustomerPortalCustomerSettings - `allow_email_change` boolean - `organization_features` CustomerOrganizationFeatureSettings — Feature flags exposed to the customer portal. - `member_model_enabled` boolean — Whether the member model is enabled for this organization. - `checkout_localization_enabled` boolean — Whether localization is enabled for this organization. - `prices` union[], required — List of enabled prices for the subscription. - union - union - LegacyRecurringProductPriceFixed — A recurring price for a product, i.e. a subscription. **Deprecated**: The recurring interval should be set on the product itself. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'fixed', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `type` 'recurring', required — The type of the price. - `recurring_interval` 'day' | 'week' | 'month' | 'year', required - `price_amount` integer, required — The price in cents. - `legacy` true, required - LegacyRecurringProductPriceCustom — A pay-what-you-want recurring price for a product, i.e. a subscription. **Deprecated**: The recurring interval should be set on the product itself. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'custom', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `type` 'recurring', required — The type of the price. - `recurring_interval` 'day' | 'week' | 'month' | 'year', required - `minimum_amount` integer, required — The minimum amount the customer can pay. If 0, the price is 'free or pay what you want'. - `maximum_amount` integer, nullable, required — The maximum amount the customer can pay. - `preset_amount` integer, nullable, required — The initial amount shown to the customer. - `legacy` true, required - union - ProductPriceFixed — A fixed price for a product. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'fixed', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `price_amount` integer, required — The price in cents. - ProductPriceCustom — A pay-what-you-want price for a product. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'custom', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `minimum_amount` integer, required — The minimum amount the customer can pay. If 0, the price is 'free or pay what you want'. - `maximum_amount` integer, nullable, required — The maximum amount the customer can pay. - `preset_amount` integer, nullable, required — The initial amount shown to the customer. - ProductPriceSeatBased — A seat-based price for a product. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'seat_based', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `seat_tiers` ProductPriceSeatTiersOutput, required — List of pricing tiers for seat-based pricing. The minimum and maximum seat limits are derived from the tiers: - minimum_seats = first tier's min_seats - maximum_seats = last tier's max_seats (None for unlimited) - `seat_tier_type` 'volume' | 'graduated' - `tiers` ProductPriceSeatTier[], required — List of pricing tiers - … - `minimum_seats` integer, required — Minimum number of seats required for purchase, derived from first tier. - `maximum_seats` integer, nullable, required — Maximum number of seats allowed for purchase, derived from last tier. None for unlimited. - ProductPriceMeteredUnit — A metered, usage-based, price for a product, with a fixed unit price. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the price. - `source` 'catalog' | 'ad_hoc', required - `amount_type` 'metered_unit', required - `price_currency` string, required — The currency in which the customer will be charged. - `tax_behavior` 'location' | 'inclusive' | 'exclusive', required - `is_archived` boolean, required — Whether the price is archived and no longer available. - `product_id` string, uuid4, required — The ID of the product owning the price. - `unit_amount` string, required — The price per unit in cents. - `cap_amount` integer, nullable, required — The maximum amount in cents that can be charged, regardless of the number of units consumed. - `meter_id` string, uuid4, required — The ID of the meter associated to the price. - `meter` ProductPriceMeter, required — A meter associated to a metered price. - `id` string, uuid4, required — The ID of the object. - `name` string, required — The name of the meter. - `unit` 'scalar' | 'token' | 'custom', required - `custom_label` string, nullable, required — The label for the custom unit. - `custom_multiplier` integer, nullable, required — The multiplier to convert from base unit to display scale. - `meters` CustomerSubscriptionMeter[], required — List of meters associated with the subscription. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the object. - `consumed_units` number, required — The number of consumed units so far in this billing period. - `credited_units` integer, required — The number of credited units so far in this billing period. - `amount` integer, required — The amount due in cents so far in this billing period. - `meter_id` string, uuid4, required — The ID of the meter. - `meter` CustomerSubscriptionMeterMeter, required - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the object. - `name` string, required — The name of the meter. Will be shown on customer's invoices and usage. - `pending_update` PendingSubscriptionUpdate, required — Pending update to be applied to a subscription at the beginning of the next period. - `created_at` string, date-time, required — Creation timestamp of the object. - `modified_at` string, date-time, nullable, required — Last modification timestamp of the object. - `id` string, uuid4, required — The ID of the object. - `applies_at` string, date-time, required — The date and time when the subscription update will be applied. - `product_id` string, uuid4, nullable, required — ID of the new product to apply to the subscription. If `null`, the product won't be changed. - `seats` integer, nullable, required — Number of seats to apply to the subscription. If `null`, the number of seats won't be changed. ## Other responses - `402` — Payment required to apply the subscription update. - `403` — Customer subscription is already canceled or will be at the end of the period, the user lacks billing permissions, or pausing/resuming is not enabled for the organization. - `404` — Customer subscription was not found. - `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/versions/964f974aceff/schema)