POST /subscriptions/{subscription-id}/pause

Use this API to pause an active or non-renewing subscription. When a subscription is paused, it does not renew, and Chargebee does not generate renewal invoices for it. This allows you to temporarily suspend a customer's service without canceling the subscription.

Prerequisites & Constraints {#PreRequisites}

The Pause Subscription feature must be enabled for the site.
Only subscriptions in the active or non_renewing state can be paused.
Subscriptions with active contract_terms cannot be paused.

Impacts {#ImpactsOfTheOperation}

Subscription
If the pause_option parameter is set to immediately, the subscription's status changes to paused. The next_billing_at, pause_date, and resume_date values are updated based on the input parameters.
Unbilled Charges
If the subscription has unbilled charges and is paused immediately, you can choose to leave the charges unbilled or invoice them. If invoiced, Chargebee attempts payment collection based on the customer's auto-collection settings. If payment fails or auto-collection is not enabled, the invoice is marked as unpaid.

Use the unbilled_charges_handling parameter to set your preference.
Dunning
If the subscription has unpaid invoices in dunning and is paused immediately, you can choose to either stop or continue the dunning process.

Use the invoice_dunning_handling parameter to set your preference.
Scheduled Ramps
Any future subscription ramps (such as price or quantity changes) effective on or after the pause date are automatically deleted.
Advanced Invoices
If the subscription has an advance invoice, Chargebee creates an adjustment credit note if the invoice is unpaid or in a payment-due state. If the invoice is already paid, a refundable credit note is created.

Implementation Notes {#ImplNotes}

Before calling this API, perform the following checks:

Confirm that the subscription status is active or non_renewing. If it isn't, the API returns an invalid_state_for_pause error.
Check the has_scheduled_changes attribute. If true, either remove the scheduled changes before calling the API or avoid the operation. Otherwise, the API returns an operation_failed error.
Ensure that the contract_term attribute is not present, or if it is present, that contract_term.status is not active. Otherwise, the API returns an invalid_request error.
If a subscription is in the non_renewing state and you want to set the pause date to a future date, the pause date must be earlier than the cancellation date. If you specify a resume date, it must also be earlier than the cancellation date.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`subscription-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`skip_billing_cycles`	Integer	No	The number of subscription billing cycles that will be skipped. The subscription resumes after the set number of billing cycles have been skipped. This is applicable only when the value of of pause_option is `billing_cycles`.
`pause_date`	Integer	No	Date on which the subscription will be paused. Applicable when `specific_date` option is chosen in the pause_option field. For non-renewing subscriptions, `pause_date` should be before the cancellation date.
`resume_date`	Integer	No	For a paused subscription, it is the date/time when the subscription is scheduled to resume. If the pause is for an indefinite period, this value is not returned. For non-renewing subscriptions,`resume_date` should be before the cancellation date.
`pause_option`	String	No	List of options to pause the subscription. * billing_cycles - Pause at the end of the current term, and resume automatically after the set number of billing cycles (in skip_billing_cycles) have been skipped * immediately - Pause immediately * end_of_term - Pause at the end of current term * specific_date - Pause on a specific date Possible values: `"end_of_term"` `"immediately"` `"billing_cycles"` `"specific_date"`
`unbilled_charges_handling`	String	No	Applicable when unbilled charges are present for the subscription and pause_option is set as `immediately`. Note: On the invoice raised, an automatic charge is attempted on the payment method available, if customer's auto-collection property is set to `on`. * invoice - Invoice charges If `invoice` is chosen, an automatic charge is attempted on the payment method available if the customer has enabled auto-collection. If a payment collection fails or when auto-collection is not enabled, the invoice is closed as unpaid. * no_action - Retain as unbilled If `no_action` is chosen, charges are added to the resumption invoice. Possible values: `"no_action"` `"invoice"`
`invoice_dunning_handling`	String	No	Handles dunning for invoices already in the dunning cycle when a subscription is paused. Applicable when pause_option is set as `immediately`. If invoice is in the dunning cycle, `invoice_dunning_handing` allows you to `stop` or `continue` dunning. * continue - Continue dunning * stop - Stop dunning Possible values: `"stop"` `"continue"`

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.