ChargebeeAPI

Cancel subscription for items

Idempotency Supported
Try in API Explorer

Cancels the specified subscription.

Prerequisites & Constraints

Impacts

Subscription

  • The cancellation date-time depends on the provided parameters:
    • When the subscription does not have a contract term, use cancel_option.
    • When the subscription has a contract term, use contract_term_cancel_option.
  • The subscription status changes to cancelled when canceled.
  • If cancel_option is specified as end_of_term, or if contract_term_cancel_option is specified as end_of_subscription_billing_term, the subscription status changes to non_renewing and the subscription billing_cycles becomes 0.

Contract Terms

  • The contract term and subscription are canceled together based on the provided contract_term_cancel_option.

Ramps

If ramps are scheduled for the subscription, this operation deletes any ramps that are set to become effective on or after the subscription's cancellation date-time.

Implementation Notes

Before calling this API, perform the following checks:

  • Confirm that the subscription status is not cancelled or transferred.
  • If the subscription has a contract term, pass contract_term_cancel_option instead of cancel_option.

Use Cases

Cancel a subscription with a contract term

If the subscription has a contract term, you can use the following parameters with this API:

  • contract_term_cancel_option
  • cancel_at
  • credit_option_for_current_term_charges
  • unbilled_charges_option
  • account_receivables_handling
  • refundable_credits_handling

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/subscriptions/{subscription-id}/cancel_for_items

Input Parameters

cancel_option
optional, enumerated string
If the subscription does not have a contract term:

Determines when to cancel the subscription.

If the subscription has a contract term:

This parameter is not applicable.

Possible Enum Values
immediately

This is used to cancel the subscription with immediate effect

end_of_term

This is used to cancel a subscription at the end of the current billing cycle

specific_date

This is used to cancel a subscription on a specified date. The change occurs as of the date/time defined in cancel_at

end_of_billing_term

This is used to cancel a subscription either at the end of the advance term, if it's billed for future renewals or at the end of its current billing cycle

end_of_term
optional, boolean, default=false

(Deprecated) Use cancel_option instead. Applicable only when the subscription does not have contract terms. Set this to true if you want to cancel the subscription at the end of the current subscription billing cycle. The subscription status changes to non_renewing.

cancel_at
optional, timestamp(UTC) in seconds
If the subscription does not have a contract term:

Specifies the date and time when the subscription should be canceled. Do not use this parameter when end_of_term is set to true.

If the subscription has a contract term:

Applicable only when contract_term_cancel_option is specific_date. Specifies the date and time to cancel the subscription and contract term.

Backdating

You can set a past date to backdate the cancellation. Backdating is allowed only if the following conditions are met:

  • Backdating is enabled for subscription cancellation.
  • The current date does not exceed the backdating limit configured in Chargebee Billing.
  • The date is on or after the current_term_start.
  • The date is on or after the most recent change involving:
    • Addition/change/removal of plan or addon item prices.
    • Addition of charge item prices.
  • The date is not more than one billing period into the past. For example, if the plan's billing period is two months and today is April 14, cancel_at cannot be earlier than February 14.
credit_option_for_current_term_charges
optional, enumerated string
If the subscription does not have a contract term:

Specifies how to handle credits for current term charges when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle credits for current term charges when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible Enum Values
none

No credits notes are created.

prorate

Prorated credits are issued.

full

Credits are issues for the full value of the current term charges.

unbilled_charges_option
optional, enumerated string
If the subscription does not have a contract term:

Specifies how to handle unbilled charges when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle unbilled charges when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible Enum Values
invoice

An invoice is generated immediately with the unbilled charges.

delete

The unbilled charges are deleted.

account_receivables_handling
optional, enumerated string
If the subscription does not have a contract term:

Specifies how to handle past due invoices when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle past due invoices when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible Enum Values
no_action

No action is taken.

schedule_payment_collection

Applies excess payments and refundable credits to past due invoices. If any amount remains and auto_collection is on , the remaining amount is automatically charged to the available payment method.

write_off

Applies excess payments and refundable credits to past due invoices. Any remaining balance is written off.
Note: The credit note for the write-off is not included in the API response.

refundable_credits_handling
optional, enumerated string
If the subscription does not have a contract term:

Specifies how to handle refundable credits when canceling immediately (i.e., cancel_option is immediately). If not specified, the site-level setting is used.

If the subscription has a contract term:

Specifies how to handle refundable credits when contract_term_cancel_option is terminate_immediately. If not specified, the site-level setting is used.

Possible Enum Values
no_action

No action is taken.

schedule_refund

Refunds remaining credits after applying them to any past due invoices.

contract_term_cancel_option
optional, enumerated string

Required when the subscription has a contract term. Determines when to cancel the subscription along with the contract term.

Possible Enum Values
terminate_immediately

Cancels the subscription and contract term immediately. Sets the contract term's status to terminated and collects any termination fee, if applicable.
To specify the termination fee, include a single object in the subscription_items array. If not specified, the default termination fee is applied (if configured).

end_of_contract_term

Prevents the contract term from renewing and schedules the subscription for cancellation at the end of the contract term.

specific_date

Cancels the subscription and contract term on the date specified by cancel_at. Sets action_at_term_end to cancel.
Note: Contact Chargebee Support to enable this option for your Chargebee site.

end_of_subscription_billing_term

Cancels the subscription and contract term at the end of the current billing cycle. Sets action_at_term_end to cancel.
Note: Contact Chargebee Support to enable this option for your Chargebee site.

invoice_date
optional, timestamp(UTC) in seconds

The document date displayed on the invoice PDF. The default value is the current date. Provide this value to backdate the invoice. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription is effective as of a past date. Moreover, if create_pending_invoices is true , and if the site is configured to set invoice dates to date of closing, then upon invoice closure, this date is changed to the invoice closing date. taxes and line_item_taxes are computed based on the tax configuration as of invoice_date. When passing this parameter, the following prerequisites must be met:

  • invoice_date must be in the past.
  • invoice_date is not more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
  • It is not earlier than cancel_at. .
cancel_reason_code
optional, string, max chars=100

Reason code for canceling the subscription. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Subscriptions > Subscription Cancellation. Must be passed if set as mandatory in the app. The codes are case-sensitive.

decommissioned
optional, boolean, default=false

Indicates whether the subscription should be decommissioned when it is canceled. If set to true all subscription operations will be disabled except deletion.

Note: Decommission operation is irreversible. Once set to true it cannot be updated to false and thus subscription will remain decommissioned permanently.

subscription_items
optional, string

Parameters for subscription_items

Returns

subscriptionSubscription object

Resource object representing subscription

customerCustomer object

Resource object representing customer

cardCard object

Resource object representing card

invoiceInvoice object

Resource object representing invoice

unbilled_chargesoptional

Resource object representing unbilled_charge

credit_notesoptional

Resource object representing credit_note