Subscriptions API

Set Up and Manage a Subscription Plan

You create and manage a subscription plan using the Catalog API. After creating a plan, you add subscriptions using the Subscriptions API. The following sections provide more information about managing subscription plans.

Set up a subscription plan

A subscription plan has a name and one or more phases. For example, a subscription plan for a gym membership might offer two phases:

Phase 1: Six-week free membership.
Phase 2: Monthly price of $60, after the initial phase.

You define each phase using cadence, recurring price, and period:

Cadence. Identifies the billing interval, such as weekly or monthly. Cadence is required.
Recurring price. The amount that is charged every billing interval while the phase is in effect. You set this amount by adding the recurring_price_money field. This is a required field. To offer a free initial phase, you set this field to 0. For more information about pricing related limitations, see Requirements and Limitations .
Period. It is the number of cadences that the phase lasts. The period is required in all phases except the last phase. If not provided, the phase never ends (the subscription plan has no end date).

For the example gym membership plan, you define the phases as follows:

Phase 1 (six weeks at no cost). For this phase, the cadence is weekly, recurring_price_money is 0, and period is 6.
Phase 2 (never ends, $60 monthly). For this phase, cadence is monthly, recurring_price_money is $60, and you do not specify the period (to indicate the never ending phase).

Be aware that after creating a subscription plan, you cannot add, remove, or reorder phases. To make any of these changes, you must create a new subscription plan. You have the option to disable the current plan (see Update a subscription plan) in which case you are not able to create new subscriptions for that plan.

For information about subscription billing, see Subscription billing.

The following UpsertCatalogObject request creates the preceding gym membership two-phase subscription plan:

curl -X POST \
-H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Square-Version: 2025-01-04' \
-d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "object":{
      "type":"SUBSCRIPTION_PLAN",
      "id":"#plan",
      "subscription_plan_data":{
         "name":"Multiphase Gym Membership",
         "phases":[
            {
               "cadence":"WEEKLY",
               "periods":6,
               "recurring_price_money":{
                  "amount":0,
                  "currency":"USD"
               }
            },
            {
               "cadence":"MONTHLY",
               "recurring_price_money":{
                  "amount":6000,
                  "currency":"USD"
               }
            }
         ]
      }
   }
}' \
'https://connect.squareupsandbox.com/v2/catalog/object'

The order in which you define the phases determine the order in which they appear on the subscription. The following is an example response fragment:

{
  "catalog_object": {
    "type": "SUBSCRIPTION_PLAN",
    "id": "7VVLO7ZBEFJWZFZMCexample",
    "updated_at": "2020-07-14T14:27:27.786Z",
    "version": 1594736847786,
    "is_deleted": false,
    "present_at_all_locations": true,
    "subscription_plan_data": {
      "name": "Multiphase Gym Membership",
      "phases": [
        {
          "uid": "YHOX4TYZH7MRRDZSC36B73B4",
          "cadence": "WEEKLY",
          "periods": 6,
          "recurring_price_money": {
            "amount": 0,
            "currency": "USD"
          },
          "ordinal": 0
        },
        {
          "uid": "OYU6OOE46DZS4LQUCGQUPZGZ",
          "cadence": "MONTHLY",
          "recurring_price_money": {
            "amount": 6000,
            "currency": "USD"
          },
          "ordinal": 1
        }
      ]
    }
  },
  "id_mappings": [
    {
      "client_object_id": "#plan",
      "object_id": "7VVLO7ZBEFJWZFZMC23TNJCX"
    }
  ]
}

Retrieve a subscription plan

You can list all the subscription plans in your account or retrieve a specific subscription plan:

List subscription plans. You call ListCatalog to retrieve subscription plans. In the request, you set the types query parameter to SUBSCRIPTION_PLAN as shown:

  curl https://connect.squareupsandbox.com/v2/catalog/list?types=SUBSCRIPTION_PLAN \
  -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'

Retrieve a specific subscription plan. If you know the ID of the plan, you call RetrieveCatalogObject to retrieve it. The following example request specifies the ID of a subscription plan.

curl --location --request GET 'https://connect.squareupsandbox.com/v2/catalog/object/OLMAHLBPPKBQF33TPKMJTOK2' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}'

The following is an example response that shows an object of the SUBSCRIPTION_PLAN type:

{
  "object": {
    "type": "SUBSCRIPTION_PLAN",
    "id": "7VVLO7ZBEFJWZFZMC23TNJCX",
    "updated_at": "2020-07-14T14:27:27.786Z",
    "version": 1594736847786,
    "is_deleted": false,
    "present_at_all_locations": true,
    "subscription_plan_data": {
      "name": "Multiphase Gym Membership",
      "phases": [
        {
          "uid": "YHOX4TYZH7MRRDZSC36B73B4",
          "cadence": "WEEKLY",
          "periods": 6,
          "recurring_price_money": {
            "amount": 0,
            "currency": "USD"
          },
          "ordinal": 0
        },
        {
          "uid": "OYU6OOE46DZS4LQUCGQUPZGZ",
          "cadence": "MONTHLY",
          "recurring_price_money": {
            "amount": 6000,
            "currency": "USD"
          },
          "ordinal": 1
        }
      ]
    }
  }
}

Update a subscription plan

You call UpsertCatalogObject to update a subscription plan. The plan ID and version number are required to update a subscription plan.

You can update only the subscription plan name and phase prices. To change any other plan fields, you must create a new subscription plan.

When you change a subscription plan name or a phase price, it reflects immediately on any existing subscriptions for the plan. If you do not want this to happen, you can create another subscription plan. In this case, you have two active subscription plans and you can create subscriptions in both these plans. You can optionally disable the existing plan by setting the enabled_at_all_locations field to false. When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

To update a subscription plan, simply include the subscription_plan object in the request body with the updates you want to apply. This is a two-step process:

Retrieve the subscription plan using RetrieveCatalogObject. The response includes the entire subscription plan.
Include the plan, with updates you want, in a UpsertCatalogObject call.

The following is an example UpsertCatalogObject. In this example, we take the example plan returned by the RetrieveCatalogObject example in the preceding section and update two things:

Change the plan name.

Set the first phase price from $0 to $1.

curl -X POST \
 -H "Authorization: Bearer {{SANDBOX_ACCESS_TOKEN}}" \
 -H 'Accept: application/json' \
 -H "Content-Type: application/json" \
 -d '{
   "idempotency_key":"{{UNIQUE_KEY}}",
   "object": {
        "type": "SUBSCRIPTION_PLAN",
        "id": "7VVLO7ZBEFJWZFZMC23TNJCX",
        "version": 1594736847786,
        "present_at_all_locations": true,
        "subscription_plan_data": {
          "name": "Multiphase Gym Membership V2-no free phase",
          "phases": [
            {
              "uid": "YHOX4TYZH7MRRDZSC36B73B4",
              "cadence": "WEEKLY",
              "periods": 6,
              "recurring_price_money": {
                "amount": 100,
                "currency": "USD"
              },
              "ordinal": 0
            },
            {
              "uid": "OYU6OOE46DZS4LQUCGQUPZGZ",
              "cadence": "MONTHLY",
              "recurring_price_money": {
                "amount": 6000,
                "currency": "USD"
              },
              "ordinal": 1
            }
          ]
         }
      }
    }
}' \
 "https://connect.squareupsandbox.com/v2/catalog/object"

The response returns a catalog_object showing an updated subscription plan:

{
   "catalog_object":{
       ...
   }
}

If you change the price of a phase, the new price takes effect the next time the customer is charged.

Delete a subscription plan

In the current implementation, you cannot delete a subscription plan.

You can optionally disable the existing plan by setting the present_at_all_locations field to false by calling UpsertCatalogObject. For more information, see Update a subscription plan. When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

Set Up and Manage a Subscription Plan

On this page

Set up a subscription plan

Note

Retrieve a subscription plan

Update a subscription plan

Delete a subscription plan

Related topics

Still haven't found what you are looking for?

Set Up and Manage a Subscription Plan

On this page

Set up a subscription plan Permalink Get a link to this section

Note

Retrieve a subscription plan Permalink Get a link to this section

Update a subscription plan Permalink Get a link to this section

Delete a subscription plan Permalink Get a link to this section

Related topics Permalink Get a link to this section

Still haven't found what you are looking for?

Set up a subscription plan

Retrieve a subscription plan

Update a subscription plan

Delete a subscription plan

Related topics