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.

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

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: A six-week free membership.

  • Phase 2: A 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. For more information, see cadence in SubscriptionPhase.

  • 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. 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).

Note

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:

Upsert Catalog Object
  • 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
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -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"
            }
          }
        ]
      }
    }
  }'

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

About the free-trial phase in a plan Permalink Get a link to this section

The following determine whether a subscription plan offers a free-trial phase:

  • The plan defines more than one phase.

  • The first phase in the plan has the price set to 0.

For example, the following subscription plans do not offer a free-trial phase:

  • The plan offers a phase with the price set to 0 and the plan offers only one phase.

  • The plan offers multiple phases but the first phase price is greater than zero.

Retrieve a subscription plan Permalink Get a link to this section

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:

    List Catalog
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/catalog/list?types=SUBSCRIPTION_PLAN \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -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.

    Retrieve Catalog Object
    • 1
    • 2
    • 3
    • 4
    curl https://connect.squareupsandbox.com/v2/catalog/object/{object_id} \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json'

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

Disable a subscription plan Permalink Get a link to this section

You cannot update a subscription plan except to disable or enable the plan. When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

You call UpsertCatalogObject to disable or enable a subscription plan. The plan ID and version number are required to disable a subscription plan. The following example disables a plan at all locations:

Upsert Catalog Object
  • 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
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "object": {
      "type": "SUBSCRIPTION_PLAN",
      "id": "5DN2Y743TQ62E2NDFGNRBHA4",
      "updated_at": "2021-06-07T15:07:58.535Z",
      "version": 1623078478535,
      "is_deleted": false,
      "present_at_all_locations": false,
      "subscription_plan_data": {
        "name": "Monthly Gym membership",
        "phases": [
          {
            "uid": "7HHEMPF3XA5IKZFVFOTZO4VD",
            "cadence": "MONTHLY",
            "recurring_price_money": {
              "amount": 6000,
              "currency": "USD"
            },
            "ordinal": 0
          }
        ]
      }
    }
  }'

You can disable or enable the existing plan's availability at locations by setting the present_at_all_locations field (along with absent_at_location_ids and present_at_location_ids) to manage subscription plan availability at specific locations.

Delete a subscription plan Permalink Get a link to this section

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.

Requirements and Limitations Permalink Get a link to this section

  • Subscription plans you create do not show up as items in the seller dashboard. You can use the Catalog API to access the subscription plans. For more information, see Retrieve a subscription plan.

Related topics Permalink Get a link to this section