Learn how to swap plan variations in a subscription using the Subscriptions API.
Docs Home
Dev Essentials
Payments Commerce Customers Staff Merchants
Partnerships
Release notes

Docs

Docs Home
Dev Essentials
Payments
Commerce
Customers
Staff
Merchants
Partnerships
Release notes
Docs
Subscriptions API

Swap Subscription Plan Variations Beta release
This is pre-release documentation for an API in public beta and is subject to change.

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.

Swap Plan
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/swap-plan \
  -X POST \
  -H 'Square-Version: 2023-08-16' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "new_plan_variation_id": "FQ7CDXXWSLUJRPM3GFJSJGZ7",
    "phases": [
      {
        "ordinal": 0,
        "order_template_id": "uhhnjH9osVv3shUADwaC0b3hNxQZY"
      }
    ]
  }'
Try in API Explorer

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.

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
  • 39
  • 40
  • 41
{
  "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"
          }
      ]
    }
  ]
}