Learn how to set up a Square subscription plan using the Catalog 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

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.

Link to section
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: A 6-week free membership.

  • Phase 2: A monthly price of $60, after the initial phase.

You define each phase using a 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 (6 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 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 and invoices.

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: 2023-05-17' \
  -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"
            }
          }
        ]
      }
    }
  }'
Try in API Explorer

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

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

Link to section
About the free-trial phase in a plan

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.

Link to section
Retrieve a subscription plan

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

  • List subscription plans. Call ListCatalog to retrieve subscription plans. In the request, 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: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

  • Retrieve a specific subscription plan. If you know the ID of the plan, 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: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'
    Try in API Explorer

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

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

Link to section
Rename a subscription plan

You might need to rename a subscription plan after it is created (for example, if you need to correct a typo or give the plan a more descriptive title).

To rename a subscription plan, call the UpsertCatalogObject or BatchUpsertCatalogObjects endpoint, specifying the updated CatalogSubscriptionPlan object containing the new plan name.

Suppose you created a subscription plan named "Magic Powers". The following example shows how to call UpsertCatalogObject to rename it as "30-Day Supply of Magic Powers" to provide more information:

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
curl https://connect.squareupsandbox.com/v2/catalog/object \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "object": {
      "type": "SUBSCRIPTION_PLAN",
      "id": "7UC3NMI7OJFGJJZTQLCZR5IW",
      "updated_at": "2021-10-20T19:28:01.492Z",
      "version": 1633462081492,
      "is_deleted": false,
      "present_at_all_locations": true,
      "subscription_plan_data": {
        "name": "30-Day Supply of Magic Powers",
        "phases": [
          {
            "uid": "O3C54EWLR6K5NRJRTIRM5QG3",
            "cadence": "THIRTY_DAYS",
            "periods": 3,
            "recurring_price_money": {
              "amount": 500,
              "currency": "USD"
            },
            "ordinal": 0
          }
        ]
      }
    }
  }'
Try in API Explorer

Link to section
Disable a subscription plan

When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

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: 2023-05-17' \
  -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
          }
        ]
      }
    }
  }'
Try in API Explorer

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.

Link to section
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 Disable a subscription plan. When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

Link to section
Requirements and limitations

Subscription plans you create do not appear 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.

Link to section
Related topics

On this page
We've made improvements to our docs.
Prefer the old format?