Billing

Extend free trial for a subscription item

Changed on

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.

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

Path parameters

subscription_item_idstring required

The ID of the subscription item to extend the free trial for

Request body

extend_tostring date-time required

RFC3339 timestamp to extend the free trial to. Must be in the future and not more than 365 days from now.

Example request

{
  "extend_to": "2026-01-08T00:00:00Z"
}

Response

A commerce subscription item.

object'commerce_subscription_item' required

String representing the object's type. Objects of the same type share the same value.

idstring required

Unique identifier for the subscription item.

instance_idstring required

Unique identifier for the Clerk instance.

status'active' | 'ended' | 'past_due' | 'upcoming' | 'incomplete' | 'abandoned' required

Current status of the subscription item.

plan_idstring required

Unique identifier for the associated plan.

price_idstring

Unique identifier for the associated price

plan_period'month' | 'annual' required

The billing period for this subscription.

payment_source_idstring required

Unique identifier for the payment source.

payer_idstring required

Unique identifier for the payer.

is_free_trialboolean required

Whether this subscription is currently on a free trial.

period_startinteger nullable

Unix timestamp (in milliseconds) when the current period started.

period_endinteger nullable

Unix timestamp (in milliseconds) when the current period ends.

proration_datestring required

Date used for proration calculations.

canceled_atinteger nullable

Unix timestamp (in milliseconds) when the subscription was canceled.

past_due_atinteger nullable

Unix timestamp (in milliseconds) when the subscription became past due.

ended_atinteger nullable

Unix timestamp (in milliseconds) when the subscription ended.

created_atinteger required

Unix timestamp (in milliseconds) when the subscription was created.

updated_atinteger required

Unix timestamp (in milliseconds) when the subscription was last updated.

Changes

  • 2025-11-10b45c56a4eed9Revision changes
    • info

      added to the response property allOf list for the response status

    • info

      added to the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

  • 2025-11-104db0b9e2d5e6Revision changes
    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status