Pause, Resume, or Cancel Subscriptions

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 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:

{
  "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 the pause_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:

{
 "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 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.

  {
  "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"
    }
  ]
}