Applies to: Subscriptions API
Learn how to pause, resume, or cancel a subscription using the Subscriptions API.
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 PauseSubscriptionid
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
actionstatus
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:
Pause subscription
The following is an example response:
{ "subscription": { "id": "3d755d2e-bfc8-410c-822e-219f5c515cfe", "location_id": "LS41RG22G3RNG", "plan_variation_id": "LOTN2MFIA57JWLRQEFLA2QDX", "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4", "start_date": "2022-09-30", "charged_through_date": "2023-05-31", "status": "ACTIVE", "invoice_ids": [ "inv:0-ChDByALzpCEdISQ_YUcd3wfuEKsI" ], "version": 1, "created_at": "2022-09-30T20:32:45Z", "timezone": "UTC", "source": { "name": "my iOS App" } }, "actions": [ { "id": "99b2439e-63f7-3ad5-95f7-ab2447a80673", "type": "PAUSE", "effective_date": "2023-05-31" } ] }
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 ResumeSubscriptionsubscription 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.
Resume subscription
The following is an example response:
{ "subscription": { "id": "48f65b20-991b-4fb0-b312-66dad7207b16", "location_id": "LS41RG22G3RNG", "plan_variation_id": "LOTN2MFIA57JWLRQEFLA2QDX", "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4", "start_date": "2022-09-30", "charged_through_date": "2023-10-30", "status": "PAUSED", "invoice_ids": [ "inv:0-ChCtK-IEx5dSky0gP_ylQ6ZCEKsI" ], "version": 1, "created_at": "2021-09-30T20:30:59Z", "timezone": "UTC", "source": { "name": "My iOS App" } }, "actions": [ { "id": "99b2439e-63f7-3ad5-95f7-ab2447a80673", "type": "PAUSE", "effective_date": "2023-10-30" }, { "id": "18ff74f4-3da4-30c5-929f-7d6fca84f115", "type": "RESUME", "effective_date": "2023-06-08" } ] }
When called, a RESUME
actionRESUME
action is already scheduled, you must first cancel the pending action
When you cancel a subscription, the canceled_date
field is set to the end of the active billing cycle and a CANCEL
actionstatus
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.
Cancel subscription
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.
{ "subscription": { "id": "8d17e86c-057e-41c4-b4be-783e94ac4d7a", "location_id": "LS41RG22G3RNG", "plan_variation_id": "LOTN2MFIA57JWLRQEFLA2QDX", "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4", "start_date": "2021-09-30", "canceled_date": "2021-11-29", "charged_through_date": "2021-11-29", "status": "ACTIVE", "invoice_ids": [ "inv:0-ChB6OFDf3lO1jAXecZ_u4vT_EKsI", "inv:0-ChBjEJT6X2XV0D06PbGl8H-TEKsI" ], "version": 1, "created_at": "2021-09-30T20:36:24Z", "timezone": "UTC", "source": { "name": "My iOS App" } }, "actions": [ { "id": "10aec353-53f9-3409-aa71-c38654c3d402", "type": "CANCEL", "effective_date": "2021-11-29" } ] }