--- title: "Extend free trial for a subscription item" method: POST path: "/billing/subscription_items/{subscription_item_id}/extend_free_trial" tags: ["Billing"] --- # Extend free trial for a subscription item `POST /billing/subscription_items/{subscription_item_id}/extend_free_trial` ## Request - Base URL: `https://api.clerk.com/v1` - URL: `https://api.clerk.com/v1/billing/subscription_items/{subscription_item_id}/extend_free_trial` - Auth: HTTP bearer Extends the free trial period for a specific subscription item to the specified timestamp. The subscription item must be currently in a free trial period, and the plan must support free trials. The timestamp must be in the future and not more than 365 days from the end of the current trial period This operation is idempotent - repeated requests with the same timestamp will not change the trial period. ## Path parameters - `subscription_item_id` string, required ## Request body - ExtendFreeTrialRequest - `extend_to` string, date-time, required: RFC3339 timestamp to extend the free trial to. Must be in the future and not more than 365 days from now. ## Response `200` A commerce subscription item. - CommerceSubscriptionItem2 - `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 - `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., "$"). - `credits` CommerceCreditsResponse - `proration` CommerceProrationCreditDetailResponse, required - `amount` 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., "$"). - `cycle_days_remaining` integer, required - `cycle_days_total` integer, required - `cycle_remaining_percent` number, double, required - `payer` CommercePayerCreditResponse, required - `remaining_balance` 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., "$"). - `applied_amount` 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., "$"). - `discounts` CommerceDiscountsResponse - `proration` CommerceProrationDiscountResponse, required - `amount` 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., "$"). - `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 - `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., "$"). - `credits` CommerceCreditsResponse - `proration` CommerceProrationCreditDetailResponse, required - `amount` 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., "$"). - `cycle_days_remaining` integer, required - `cycle_days_total` integer, required - `cycle_remaining_percent` number, double, required - `payer` CommercePayerCreditResponse, required - `remaining_balance` 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., "$"). - `applied_amount` 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., "$"). - `discounts` CommerceDiscountsResponse - `proration` CommerceProrationDiscountResponse, required - `amount` 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., "$"). - `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. ## Other responses - `400`: Request was not successful - `401`: Authentication invalid - `403`: Authorization invalid - `404`: Resource not found - `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 `payer` response property `allOf` list for the response status `200` - added `#/components/schemas/CommercePlan-2` to the `plan` response property `allOf` list for the response status `200` - removed `#/components/schemas/schemas-CommercePayerResponse` from the `payer` response property `allOf` list for the response status `200` - removed `#/components/schemas/schemas-CommercePlan` from the `plan` response property `allOf` list for the response status `200` - **2026-06-04** (2025-11-10) `4db0b9e2d5e6`: 4 info - added the optional property `next_invoice/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/per_unit_totals` to the response with the `200` status - added the optional property `next_invoice/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/totals` to the response with the `200` status - added the optional property `next_payment/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/per_unit_totals` to the response with the `200` status - added the optional property `next_payment/allOf[#/components/schemas/CommerceSubscriptionItemNextPaymentResponse]/totals` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/clerk/apis/clerk-backend-api/changes/billing/subscription_items/:subscription_item_id/extend_free_trial/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)