--- title: "Cancel a subscription item" method: DELETE path: "/billing/subscription_items/{subscription_item_id}" tags: ["Billing"] --- # Cancel a subscription item `DELETE /billing/subscription_items/{subscription_item_id}` Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period. ## Path parameters - `subscription_item_id` string, required ## Query parameters - `end_now` boolean ## Response `200` A commerce subscription item. - CommerceSubscriptionItem - `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' | 'canceled' | 'expired' | '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. - `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., "$"). - `plan_id` string, nullable, required — Unique identifier for the associated plan. - `price_id` string — Unique identifier for the associated price - `plan` CommercePlan - `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 plan. - `name` string, required — The name of the 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., "$"). - `description` string, nullable, required — The description of the 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. - `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, nullable, required — The URL of the plan's avatar image. - `features` FeatureResponse[] — 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, nullable, required — The description of the feature. - `slug` string, required — The URL-friendly slug for the feature. - `avatar_url` string, nullable, required — The URL of the feature's avatar image. - `free_trial_enabled` boolean, required — Whether free trial is enabled for this plan. - `free_trial_days` integer, nullable, required — Number of free trial days for this plan. - `unit_prices` CommercePlanUnitPrice[] — Per-unit pricing tiers for this plan (for example, seats) - `name` string, required — Name of the billable unit (for example, seats) - `block_size` integer, required — Number of units included in each pricing block - `tiers` CommercePlanUnitPriceTier[], required — Tiered pricing configuration for this unit - `starts_at_block` integer, required — Start block (inclusive) for this tier - `ends_after_block` integer, nullable — End block (inclusive) for 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., "$"). - `plan_period` 'month' | 'annual', required — The billing period for this subscription item. - `payment_method` CommercePaymentMethodResponse - `object` 'commerce_payment_method', required — String representing the object's type. Objects of the same type share the same value. - `id` string, required — Unique identifier for the payment method. - `payer_id` string, required — Unique identifier for the payer. - `payment_type` 'card' | 'link' | 'payer-credits', required — The payment method type. - `is_default` boolean — Whether this is the default payment method 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, required — External account ID in the payment gateway. - `last4` string, nullable, required — Last 4 digits of the card (for card payment methods). - `status` 'active' | 'disconnected', required — Status of the payment method. - `wallet_type` string, nullable — Type of wallet (if applicable). - `card_type` string, nullable, required — Type of card (if applicable). - `expiry_year` integer, nullable — Card expiration year (for card payment methods). - `expiry_month` integer, nullable — Card expiration month (for card payment methods). - `created_at` integer — Unix timestamp (in milliseconds) when the payment method was created. - `updated_at` integer — Unix timestamp (in milliseconds) when the payment method was last updated. - `is_removable` boolean — Whether this payment method 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., "$"). - `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` CommercePayerResponse - `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, nullable — User ID for user-type payers. - `first_name` string, nullable — First name of the payer. - `last_name` string, nullable — Last name of the payer. - `email` string, nullable — Email address of the payer. - `organization_id` string, nullable — Organization ID for org-type payers. - `organization_name` string, nullable — Organization name for org-type payers. - `image_url` string — 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 — Unix timestamp (in milliseconds) when the payer was created. - `updated_at` integer — Unix timestamp (in milliseconds) when the payer was last updated. - `is_free_trial` boolean, required — Whether this subscription item includes a free trial. - `period_start` integer, required — Unix timestamp (in milliseconds) when the current period started. - `period_end` integer, nullable, required — Unix timestamp (in milliseconds) when the current period ends. - `proration_date` string, date — The day the subscription item was prorated from. Only available in some responses. - `canceled_at` integer, nullable, required — Unix timestamp (in milliseconds) when the subscription item was canceled. - `past_due_at` integer, nullable, required — Unix timestamp (in milliseconds) when the subscription item became past due. - `ended_at` integer, nullable, required — Unix timestamp (in milliseconds) when the subscription item ended. - `created_at` integer — Unix timestamp (in milliseconds) when the subscription item was created. - `updated_at` integer — Unix timestamp (in milliseconds) when the subscription item was last updated. - `seats` CommerceSubscriptionItemSeatsResponse - `quantity` integer, nullable, required — Seat quantity being billed; null means unlimited - `tiers` CommercePerUnitTotalTier2[] — Per-unit cost breakdown by 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` CommerceTotalsResponse2 - `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` CommercePerUnitTotal2[] - `name` string, required — Name of the billable unit (for example, seats) - `block_size` integer, required — Number of units included in each pricing block - `tiers` CommercePerUnitTotalTier2[], 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` BillingDiscountsResponse - `proration` BillingProrationDiscountDetail, 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 — Number of days that have passed in the billing cycle - `cycle_days_total` integer, required — Total number of days in the billing cycle - `cycle_passed_percent` number, double, required — Percentage of the billing cycle that has passed - `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., "$"). ## 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 --- [API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/75df3a43fcb2/schema)