ChargebeeAPI

Pause a subscription

Idempotency Supported
Try in API Explorer

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

Impacts

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

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.

Sample Request

URL Format

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

Input Parameters

pause_option
optional, enumerated string

List of options to pause the subscription.

Possible Enum Values
immediately

Pause immediately

end_of_term

Pause at the end of current term

specific_date

Pause on a specific date

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

pause_date
optional, timestamp(UTC) in seconds

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.

unbilled_charges_handling
optional, enumerated string

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.

Possible Enum Values
no_action

Retain as unbilled If no_action is chosen, charges are added to the resumption invoice.

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.

invoice_dunning_handling
optional, enumerated string

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.

Possible Enum Values
continue

Continue dunning

stop

Stop dunning

skip_billing_cycles
optional, integer, min=1

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 .

resume_date
optional, timestamp(UTC) in seconds

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.

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