Clerk API (unofficial showcase)
POST/billing/subscription_items/{subscription_item_id}/extend_free_trial

Extend free trial for a subscription item

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.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 1 body field
subscription_item_idstringrequired
The ID of the subscription item to extend the free trial for

Parameters for extending the free trial

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

7 status codes
200A commerce subscription item.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:commerce_subscription_item
idstringrequired
Unique identifier for the subscription item.
instance_idstringrequired
Unique identifier for the Clerk instance.
statusstringrequired
Current status of the subscription item.
Allowed:activeendedpast_dueupcomingincompleteabandoned
creditobjectoptional
Credit information (only available in PaymentAttempt events).
plan_idstringrequired
Unique identifier for the associated plan.
price_idstringoptional
Unique identifier for the associated price
planobjectrequired
The associated commerce plan.
plan_periodstringrequired
The billing period for this subscription.
Allowed:monthannual
payment_source_idstringrequired
Unique identifier for the payment source.
payment_sourceobjectoptional
The payment source associated with this subscription.
lifetime_paidobjectoptional
Total amount paid over the lifetime of this subscription.
amountobjectoptional
Current amount for this subscription.
next_invoiceobjectoptional
Information about the next invoice.
next_paymentobjectoptional
Information about the next payment.
payer_idstringrequired
Unique identifier for the payer.
payerobjectoptional
The payer associated with this subscription.
is_free_trialbooleanrequired
Whether this subscription is currently on a free trial.
period_startintegeroptional
Unix timestamp (in milliseconds) when the current period started.
period_endintegeroptional
Unix timestamp (in milliseconds) when the current period ends.
proration_datestringrequired
Date used for proration calculations.
canceled_atintegeroptional
Unix timestamp (in milliseconds) when the subscription was canceled.
past_due_atintegeroptional
Unix timestamp (in milliseconds) when the subscription became past due.
ended_atintegeroptional
Unix timestamp (in milliseconds) when the subscription ended.
created_atintegerrequired
Unix timestamp (in milliseconds) when the subscription was created.
updated_atintegerrequired
Unix timestamp (in milliseconds) when the subscription was last updated.
400Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
401Authentication invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
403Authorization invalid
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
404Resource not found
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
422Invalid request parameters
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional
500Request was not successful
errorsarray<object>required
metaobjectoptional
clerk_trace_idstringoptional

Error handling

A 400 is returned: Request was not successful. A 401 is returned: Authentication invalid. A 403 is returned: Authorization invalid. A 404 is returned: Resource not found. A 422 is returned: Invalid request parameters. A 500 is returned: Request was not successful.