Pause, Resume, or Cancel Subscriptions
Subscriptions follow the billing cadence and timeline configured in the phases
of the associated SubscriptionPlanVariation
. Your application can change that preconfigured cadence by pausing, resuming, or canceling a customer's subscription during the billing cycle.
A subscription can be paused for a number of billing cycles without being canceled. Call PauseSubscription and include the id
of the subscription to pause. Optionally, you can include a pause_reason
and, if you know how long the subscription should be paused before being resumed, you can include either a pause_cycle_duration
(the number of billing cycles to pause) or a resume_effective_date
in the request. When called, a PAUSE
action is scheduled and the subscription is paused at the end of the current billing period. The subscription's status
is now set to PAUSED
.
For example, a gym might allow athletes to pause their monthly membership for up to 3 months in the event of an injury:
The following is an example response:
There are some restrictions when pausing a subscription:
Subscriptions cannot be paused during a free trial phase (a phase when the customer isn't charged a payment).
Subscriptions can be paused for any number of billing cycles within a single
phase
. For example, if a subscription has two billing cycles left in the current phase, it can be paused for up to two cycles only. If thepause_cycle_duration
is set beyond the current phase, the request fails and the subscription isn't paused.
To manually resume a paused or deactivated subscription, call ResumeSubscription with the desired subscription ID
, resume_effective_date
, and resume_change_timing
to indicate whether the subscription should resume immediately on the resume_effective_date
or at the end of the billing cycle for that date.
The following is an example response:
When called, a RESUME
action is scheduled. Note that if a RESUME
action is already scheduled, you must first cancel the pending action
and then call ResumeSubscription to schedule a new one.
When you cancel a subscription, the canceled_date
field is set to the end of the active billing cycle and a CANCEL
action is scheduled for the same date. After this date, the status
changes from ACTIVE
to CANCELED
. For example, if the subscription is in a phase with a monthly cadence, the canceled_date
field is set depending on when the phase started. For example:
If the phase starts on the first of the month, the
canceled_date
field is set to the end of the month.If the phase starts on March 5, the
canceled_date
field is set to April 5.
The following is an example response. The subscription_status
remains ACTIVE
; however, the canceled_date
field is set to the end of the current billing period.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.