Billing

Cancel a subscription item

Changed on

Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period.

delete/billing/subscription_items/{subscription_item_id}

Request

  • Base URL: https://api.clerk.com/v1
  • URL: https://api.clerk.com/v1/billing/subscription_items/{subscription_item_id}
  • Auth: HTTP bearer

Path parameters

subscription_item_idstring required

The ID of the subscription item to cancel

Query parameters

end_nowboolean

Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default)

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' | 'canceled' | 'expired' | 'ended' | 'past_due' | 'upcoming' | 'incomplete' | 'abandoned' required

Current status of the subscription item.

plan_idstring nullable 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 item.

payer_idstring required

Unique identifier for the payer.

is_free_trialboolean required

Whether this subscription item includes a free trial.

period_startinteger required

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

period_endinteger nullable required

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

proration_datestring date

The day the subscription item was prorated from. Only available in some responses.

canceled_atinteger nullable required

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

past_due_atinteger nullable required

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

ended_atinteger nullable required

Unix timestamp (in milliseconds) when the subscription item ended.

created_atinteger

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

updated_atinteger

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

Changes

  • 2025-11-101d47a6af3befRevision changes
    • warning

      added the new payer-credits enum value to the / response property for the response status

  • 2025-11-10b45c56a4eed9Revision changes
    • info

      added to the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status