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:

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