--- title: "Create a price transition for a subscription item" method: POST path: "/billing/subscription_items/{subscription_item_id}/price_transition" tags: ["Billing"] --- # Create a price transition for a subscription item `POST /billing/subscription_items/{subscription_item_id}/price_transition` ## Request - Base URL: `https://api.clerk.com/v1` - URL: `https://api.clerk.com/v1/billing/subscription_items/{subscription_item_id}/price_transition` - Auth: HTTP bearer Creates a price transition for the specified subscription item. This may create an upcoming subscription item or activate immediately depending on plan and payer rules. ## Path parameters - `subscription_item_id` string, required ## Request body - PriceTransitionRequest - `from_price_id` string, required: The current price ID of the subscription item. - `to_price_id` string, required: The target price ID to transition to. ## Response `200` A commerce price transition. - CommercePriceTransitionResponse - `object` 'commerce_price_transition', required: String representing the object's type. Objects of the same type share the same value. - `subscription_item` CommerceSubscriptionItem2, required - `object` 'commerce_subscription_item', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the subscription item. - `instance_id` string, required: Unique identifier for the Clerk instance. - `status` 'active' | 'ended' | 'past_due' | 'upcoming' | 'incomplete' | 'abandoned', required: Current status of the subscription item. - `credit` CommerceSubscriptionCreditResponse - `amount` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `cycle_remaining_percent` number, float: Percentage of the billing cycle remaining. - `plan_id` string, required: Unique identifier for the associated plan. - `price_id` string: Unique identifier for the associated price - `plan` CommercePlan2, required - `object` 'commerce_plan', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the commerce plan. - `name` string, required: The name of the commerce plan. - `fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `annual_monthly_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `annual_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `amount` integer, required: The amount in cents for the plan. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `annual_monthly_amount` integer, required: The monthly amount in cents when billed annually. - `annual_monthly_amount_formatted` string, required: The formatted annual monthly amount as a string. - `annual_amount` integer, required: The total annual amount in cents. - `annual_amount_formatted` string, required: The formatted annual amount as a string. - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `currency` string, required: The currency code (e.g., "USD"). - `description` string, required: The description of the commerce plan. - `product_id` string, required: The ID of the product this plan belongs to. - `is_default` boolean, required: Whether this is the default plan. - `is_recurring` boolean, required: Whether this is a recurring plan. - `publicly_visible` boolean, required: Whether this plan is publicly visible. - `has_base_fee` boolean, required: Whether this plan has a base fee. - `payer_type` string[], required: The types of payers that can use this plan. - `for_payer_type` string, required: The payer type this plan is designed for. - `slug` string, required: The URL-friendly slug for the plan. - `avatar_url` string, required: The URL of the plan's avatar image. - `period` string: The billing period for the plan. - `interval` integer: The billing interval. - `features` FeatureResponse2[], required: The features included in this plan. - `object` 'feature', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the feature. - `name` string, required: The name of the feature. - `description` string, required: The description of the feature. - `slug` string, required: The URL-friendly slug for the feature. - `avatar_url` string, required: The URL of the feature's avatar image. - `free_trial_enabled` boolean: Whether free trial is enabled for this plan. - `free_trial_days` integer, nullable: Number of free trial days for this plan. - `plan_period` 'month' | 'annual', required: The billing period for this subscription. - `payment_source_id` string, required: Unique identifier for the payment source. - `payment_source` CommercePaymentSourceResponse - `object` 'commerce_source', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the payment source. - `payer_id` string, required: Unique identifier for the payer. - `payment_method` 'card' | 'apple_pay' | 'google_pay', required: The payment method type. - `is_default` boolean, nullable: Whether this is the default payment source for the payer. - `gateway` string, required: The payment gateway. - `gateway_external_id` string, required: External ID in the payment gateway. - `gateway_external_account_id` string, nullable: External account ID in the payment gateway. - `last4` string, required: Last 4 digits of the card (for card payment sources). - `status` 'active' | 'disconnected', required: Status of the payment source. - `wallet_type` string, required: Type of wallet (if applicable). - `card_type` string, required: Type of card (if applicable). - `expiry_year` integer: Card expiration year (for card payment sources). - `expiry_month` integer: Card expiration month (for card payment sources). - `created_at` integer, required: Unix timestamp (in milliseconds) when the payment source was created. - `updated_at` integer, required: Unix timestamp (in milliseconds) when the payment source was last updated. - `is_removable` boolean, nullable: Whether this payment source can be removed. - `lifetime_paid` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `amount` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `next_invoice` CommerceSubscriptionItemNextPaymentResponse - `amount` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `date` integer, nullable: Unix timestamp (in milliseconds) for the next payment date. - `per_unit_totals` CommercePerUnitTotal[]: Per-unit total breakdown (for example, seats) for the next payment. - `name` string, required: Name of the billable unit (for example, `seats`). - `block_size` integer, required: Number of units included in each pricing block. - `tiers` CommercePerUnitTotalTier[], required: Computed totals for each pricing tier. - `quantity` integer, nullable: Units billed in this tier; null means unlimited. - `fee_per_block` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `totals` CommerceTotalsResponse - `subtotal` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `base_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `tax_total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `grand_total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `per_unit_totals` CommercePerUnitTotal[] - `name` string, required: Name of the billable unit (for example, `seats`). - `block_size` integer, required: Number of units included in each pricing block. - `tiers` CommercePerUnitTotalTier[], required: Computed totals for each pricing tier. - `quantity` integer, nullable: Units billed in this tier; null means unlimited. - `fee_per_block` CommerceMoneyResponse, required - … - `total` CommerceMoneyResponse, required - … - `credits` CommerceCreditsResponse - `proration` CommerceProrationCreditDetailResponse, required - `amount` CommerceMoneyResponse, required - … - `cycle_days_remaining` integer, required - `cycle_days_total` integer, required - `cycle_remaining_percent` number, double, required - `payer` CommercePayerCreditResponse, required - `remaining_balance` CommerceMoneyResponse, required - … - `applied_amount` CommerceMoneyResponse, required - … - `total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `discounts` CommerceDiscountsResponse - `proration` CommerceProrationDiscountResponse, required - `amount` CommerceMoneyResponse, required - … - `cycle_days_passed` integer, required - `cycle_days_total` integer, required - `cycle_passed_percent` number, float, required - `total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `next_payment` CommerceSubscriptionItemNextPaymentResponse - `amount` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `date` integer, nullable: Unix timestamp (in milliseconds) for the next payment date. - `per_unit_totals` CommercePerUnitTotal[]: Per-unit total breakdown (for example, seats) for the next payment. - `name` string, required: Name of the billable unit (for example, `seats`). - `block_size` integer, required: Number of units included in each pricing block. - `tiers` CommercePerUnitTotalTier[], required: Computed totals for each pricing tier. - `quantity` integer, nullable: Units billed in this tier; null means unlimited. - `fee_per_block` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `totals` CommerceTotalsResponse - `subtotal` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `base_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `tax_total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `grand_total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `per_unit_totals` CommercePerUnitTotal[] - `name` string, required: Name of the billable unit (for example, `seats`). - `block_size` integer, required: Number of units included in each pricing block. - `tiers` CommercePerUnitTotalTier[], required: Computed totals for each pricing tier. - `quantity` integer, nullable: Units billed in this tier; null means unlimited. - `fee_per_block` CommerceMoneyResponse, required - … - `total` CommerceMoneyResponse, required - … - `credits` CommerceCreditsResponse - `proration` CommerceProrationCreditDetailResponse, required - `amount` CommerceMoneyResponse, required - … - `cycle_days_remaining` integer, required - `cycle_days_total` integer, required - `cycle_remaining_percent` number, double, required - `payer` CommercePayerCreditResponse, required - `remaining_balance` CommerceMoneyResponse, required - … - `applied_amount` CommerceMoneyResponse, required - … - `total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `discounts` CommerceDiscountsResponse - `proration` CommerceProrationDiscountResponse, required - `amount` CommerceMoneyResponse, required - … - `cycle_days_passed` integer, required - `cycle_days_total` integer, required - `cycle_passed_percent` number, float, required - `total` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `payer_id` string, required: Unique identifier for the payer. - `payer` CommercePayerResponse2 - `object` 'commerce_payer', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the payer. - `instance_id` string, required: Unique identifier for the Clerk instance. - `user_id` string: User ID for user-type payers. - `first_name` string, required: First name of the payer. - `last_name` string, required: Last name of the payer. - `email` string, required: Email address of the payer. - `organization_id` string: Organization ID for org-type payers. - `organization_name` string: Organization name for org-type payers. - `image_url` string, required: URL of the payer's image/avatar. - `credits_balance` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `created_at` integer, required: Unix timestamp (in milliseconds) when the payer was created. - `updated_at` integer, required: Unix timestamp (in milliseconds) when the payer was last updated. - `is_free_trial` boolean, required: Whether this subscription is currently on a free trial. - `period_start` integer, nullable: Unix timestamp (in milliseconds) when the current period started. - `period_end` integer, nullable: Unix timestamp (in milliseconds) when the current period ends. - `proration_date` string, required: Date used for proration calculations. - `canceled_at` integer, nullable: Unix timestamp (in milliseconds) when the subscription was canceled. - `past_due_at` integer, nullable: Unix timestamp (in milliseconds) when the subscription became past due. - `ended_at` integer, nullable: Unix timestamp (in milliseconds) when the subscription ended. - `created_at` integer, required: Unix timestamp (in milliseconds) when the subscription was created. - `updated_at` integer, required: Unix timestamp (in milliseconds) when the subscription was last updated. - `transition` CommercePriceTransitionDetails, required - `previous_plan` CommercePlan2, required - `object` 'commerce_plan', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the commerce plan. - `name` string, required: The name of the commerce plan. - `fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `annual_monthly_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `annual_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `amount` integer, required: The amount in cents for the plan. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `annual_monthly_amount` integer, required: The monthly amount in cents when billed annually. - `annual_monthly_amount_formatted` string, required: The formatted annual monthly amount as a string. - `annual_amount` integer, required: The total annual amount in cents. - `annual_amount_formatted` string, required: The formatted annual amount as a string. - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `currency` string, required: The currency code (e.g., "USD"). - `description` string, required: The description of the commerce plan. - `product_id` string, required: The ID of the product this plan belongs to. - `is_default` boolean, required: Whether this is the default plan. - `is_recurring` boolean, required: Whether this is a recurring plan. - `publicly_visible` boolean, required: Whether this plan is publicly visible. - `has_base_fee` boolean, required: Whether this plan has a base fee. - `payer_type` string[], required: The types of payers that can use this plan. - `for_payer_type` string, required: The payer type this plan is designed for. - `slug` string, required: The URL-friendly slug for the plan. - `avatar_url` string, required: The URL of the plan's avatar image. - `period` string: The billing period for the plan. - `interval` integer: The billing interval. - `features` FeatureResponse2[], required: The features included in this plan. - `object` 'feature', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the feature. - `name` string, required: The name of the feature. - `description` string, required: The description of the feature. - `slug` string, required: The URL-friendly slug for the feature. - `avatar_url` string, required: The URL of the feature's avatar image. - `free_trial_enabled` boolean: Whether free trial is enabled for this plan. - `free_trial_days` integer, nullable: Number of free trial days for this plan. - `previous_price` BillingPriceResponse, required - `object` 'commerce_price', required: String representing the object's type. Objects of the same type share the same value. - `id` string, required: Unique identifier for the price. - `plan_id` string, required: Unique identifier for the associated plan. - `instance_id` string, required: Unique identifier for the instance. - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `amount` integer, required: The amount in cents for the price. - `annual_monthly_amount` integer, required: The monthly amount in cents when billed annually. - `fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `annual_monthly_fee` CommerceMoneyResponse, required - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `description` string, nullable: The description of the price. - `is_default` boolean, required: Whether this price is the default price for its plan. - `created_at` integer, required: Unix timestamp (milliseconds) of creation. - `supported_billing_periods` 'month' | 'annual' | 'both', required: Which billing periods this price supports. - `effective_at` integer, required: Unix timestamp (milliseconds) when the new price takes effect. - `effective_mode` 'immediate' | 'end_of_period', required: When the new price takes effect. - `next_billing_date` integer, nullable: Unix timestamp (milliseconds) for the next billing date. - `charged_immediately` boolean, required: Whether an immediate charge was made. - `immediate_charge` CommerceMoneyResponse - `amount` integer, required: The amount in cents. - `amount_formatted` string, required: The formatted amount as a string (e.g., "$49.99"). - `currency` string, required: The currency code (e.g., "USD"). - `currency_symbol` string, required: The currency symbol (e.g., "$"). - `previous_subscription_item_status` 'canceled' | 'ended' | 'abandoned', required: The status of the previous subscription item after transition. - `previous_subscription_item_id` string, required: The ID of the previous subscription item. ## Other responses - `400`: Request was not successful - `401`: Authentication invalid - `403`: Authorization invalid - `404`: Resource not found - `409`: Conflict - `422`: Invalid request parameters - `500`: Request was not successful ## Changes - **2026-06-26** (2025-11-10) `b45c56a4eed9`: 4 info - added `#/components/schemas/CommercePayerResponse-2` to the `subscription_item/payer` response property `allOf` list for the response status `200` - added `#/components/schemas/CommercePlan-2` to the `subscription_item/plan` response property `allOf` list for the response status `200` - removed `#/components/schemas/schemas-CommercePayerResponse` from the `subscription_item/payer` response property `allOf` list for the response status `200` - removed `#/components/schemas/schemas-CommercePlan` from the `subscription_item/plan` response property `allOf` list for the response status `200` - **2026-06-04** (2025-11-10) `4db0b9e2d5e6`: 5 info - added the optional property `subscription_item/next_invoice/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/per_unit_totals` to the response with the `200` status - added the optional property `subscription_item/next_invoice/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/totals` to the response with the `200` status - added the optional property `subscription_item/next_payment/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/per_unit_totals` to the response with the `200` status - added the optional property `subscription_item/next_payment/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/totals` to the response with the `200` status - …1 more - …earlier changes not shown [Operation history](https://skmtc.dev/clerk/apis/clerk-backend-api/changes/billing/subscription_items/:subscription_item_id/price_transition/post.md) --- [API](https://skmtc.dev/clerk/apis/clerk-backend-api.md) - [All operations](https://skmtc.dev/clerk/apis/clerk-backend-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clerk/apis/clerk-backend-api/revisions/a490313abffa?raw)