Swap Subscription Plan Variations

Applies to: Subscriptions API | Catalog API

Learn how to swap plan variations in a subscription using the Subscriptions API.

In cases where a customer wants to switch one subscription type for another, such as upgrading to a new or premium subscription tier, you can swap the plan variation for a customer's subscription by using the SwapPlan endpoint.

In your request, include the subscription_id to update the path. In the request body, include the ID of the new plan variation as the new_plan_variation_id, as well as a list of phases containing an ordinal and an order_template_id corresponding to those in the new plan variation.

The response returns the current Subscription object containing a new SWAP_PLAN action. The customer remains subscribed to the original plan variation until the end of the current billing cycle, at which time the new plan variation replaces the original variation. If the customer is in the middle of a billing cycle and you want to subscribe them to a new plan variation effective immediately, you must cancel the current subscription and create a new subscription with the desired plan variation.

{
  "subscription": {
    "id": "9ba40961-995a-4a3d-8c53-048c40cafc13",
    "location_id": "S8GWD5R9QB376",
    "plan_variation_id": "6JHXF3B2CW3YKHDV4XEM674H",
    "customer_id": "CHFGVKYY8RSV93M5KCYTG4PN0G",
    "status": "ACTIVE",
    "price_override_money": {
      "amount": 2000,
      "currency": "USD"
    },
    "version": 1594311617331,
    "created_at": "2021-10-20T21:53:10Z",
    "timezone": "America/Los_Angeles",
    "source": {
      "name": "My App"
    },
    "phases": [
      {
        "uid": "98d6f53b-40e1-4714-8827-032fd923be25",
        "ordinal": 0,
        "order_template_id": "E6oBY5WfQ2eN4pkYZwq4ka6n7KeZY",
        "plan_phase_uid": "C66BKH3ASTDYGJJCEZXQQSS7"
      }
    ]
  },
  "actions": [
    {
      "id": "f0a1dfdc-675b-3a14-a640-99f7ac1cee83",
      "type": "SWAP_PLAN",
      "effective_date": "2021-11-17",
      "new_plan_variation_id": "FQ7CDXXWSLUJRPM3GFJSJGZ7",
      "phases": [
          {
              "ordinal": 0,
              "order_template_id": "uhhnjH9osVv3shUADwaC0b3hNxQZY"
          }
      ]
    }
  ]
}

Sometimes a seller might want to make changes to a plan variation and have them take effect for every subscriber (for example, increasing the price of a subscription tier or setting a consistent monthly_billing_anchor_date. In order to do so, your application must take the following actions:

• Load details of the current plan variation using RetrieveCatalogObject.
• Create a new CatalogSubscriptionPlanVariation using UpsertCatalogObject, keeping all details the same as the old variation except for what you want to change (such as the phases.subscription_pricing or monthly_billing_anchor_date field).
• Take note of the id values for the original variation and the new one you just created.
• Call BulkSwapPlan with the old_plan_variation_id and new_plan_variation_id sets. This swaps the subscriptions of every customer subscribed to the old plan variation. At the time of their next bill, each customer is automatically subscribed to the new plan variation.
• (optional) If you no longer want any subscriptions to the original plan variation, deprecate the original variation by calling UpsertCatalogObject and setting present_at_all_locations to false. This effectively “deactivates” the plan variation, ensuring that no new subscriptions can be created. If you deactivate a plan variation in this way, set the successor_plan_variation_id to the id of the new plan variation that replaces it.

The following BulkSwapPlan request schedules a SWAP_PLAN action for all active subscriptions under one plan variation. At the end of each subscriber's billing cycle, they are subscribed to the new plan variation.

The response shows the number of affected subscriptions.

{
  "affected_subscriptions": 47
}