Subscriptions API

Manage Subscriptions Using the Subscriptions API

After setting up a subscription plan (see Set up and Manage a Subscription Plan), you can use the Subscriptions API to create and manage subscriptions.

Subscription object
Manage enrollments in a subscription plan
Subscription price override
Requirements and limitations
Webhooks
Additional considerations
Related topics

Subscription object
Manage enrollments in a subscription plan
Create subscriptions
Update subscriptions
Retrieve subscriptions
Pause subscriptions
Resume subscriptions
Cancel subscriptions
Swap subscription plans
Subscription price override
Example 1
Example 2
Example 3
Requirements and limitations
Webhooks
Additional considerations
Subscription billing and invoices
Subscription actions
Subscription events
Deactivated subscriptions
Related topics

Link to section
Subscription object

The Subscription API provides the Subscription type that represents a subscription. In addition to storing basic subscription information (customer ID and associated plan ID), the type provides fields that you can optionally customize including:

Payment source information (card_id). By default, when you create a subscription, Square sends an invoice to the customer's email address. Optionally, a card on file can be linked with the subscription so that Square can charge the card and email a receipt for the invoice. ACH payments are not possible through the Subscriptions API because bank account sources cannot be stored on file and charged later.
Subscription start date (start_date). By default, the subscription starts as soon as you create a subscription. You can optionally configure a start date to start the subscription some time in future. Initially, these subscriptions have a status of PENDING and become ACTIVE on the start date. The start date is effective at midnight for the specified timezone.
Tax percentage (tax_percentage). By default, taxes are not added to the subscription invoice. You can optionally specify a tax percentage when creating individual subscriptions. For example, depending on the business location you might configure different tax rates. Square then bills the customer for both the subscription and taxes.
Override subscription price (price_override_money). By default, the subscription plan determines the subscription price (see Set up and Manage a Subscription Plan). However, individual subscriptions can optionally override that amount. For more information, see Subscription price override.
Subscription cancellation date (canceled_date). By default, the subscription plan dictates if and when a subscription ends. You also have the option to call CancelSubscription to cancel a subscription.

Note

If you set the canceled_date, the subscription cancels on the specified date and the final bill is prorated accordingly. However, if you call CancelSubscription, the subscriptions cancels at the end of the current billing cycle.

Link to section
Manage enrollments in a subscription plan

You use the Subscriptions API to create and manage subscriptions.

Link to section
Create subscriptions

You call CreateSubscription to enroll a customer in a subscription plan. In the request, you provide a customer ID, a plan ID, and a location ID to associate with the subscription. The customer ID refers to the customer profile in the seller's Customer Directory (see Customers API Overview).

The customer profiles must include a valid email address. Square emails the subscription invoices and the receipts to this email address.

You can also customize individual subscriptions.

The following are example CreateSubscription requests:

Example 1: Create a subscription. The following CreateSubscription request specifies the minimum required fields:

Create Subscription

1
2
3
4
5
6
7
8
9
10
11

curl https://connect.squareupsandbox.com/v2/subscriptions \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "location_id": "{LOCATION_ID}",
    "plan_id": "{PLAN_ID}",
    "customer_id": "{CUSTOMER_ID}"
  }'

The following is an example response:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
"subscription": {
  "id": "e4481142-4484-4218-951d-89a050c11111",
  "location_id": "S8GWD5R9QB376",
  "plan_id": "3ZODVTLGZVTS6PGBY525H4HQ",
  "customer_id": "7FCET7VZ0CTKZ6FXN6HXWVWNG0",
  "start_date": "2020-08-04",
  "status": "ACTIVE",
  "version": 1596557182154,
  "created_at": "2020-08-04T16:06:21Z",
  "timezone": "Etc/UTC"
}
}

Note the following:

The request does not specify card_id, the customer's card on file; therefore, Square sends the invoice to the customer's email address.
The request does not specify start_date; therefore, the subscription starts immediately.
If the plan offers a free phase, Square bills the subscription only after the free phase; otherwise, billing occurs immediately.
To test an end-to-end experience, see Walkthrough: Create a Subscription Plan and Manage Subscriptions.

Example 2: Create subscriptions with customization. The following CreateSubscription call specifies optional configurations:
- start_date of the subscription, some future date (YYYY-MM-DD).
- card_id identifies the card on file to charge.
- price_override_money specifies a custom price ($5) for the subscription. The price overrides the price configured in the plan (see Set up and Manage a Subscription Plan).
- tax_percentage to add to the invoice. The example shows a 5% tax.
- timezone indicates that the subscription date is relative to the "America/Los_Angeles" timezone. The timezone is the IANA Timezone Database identifier for the timezone (for example, America/Los_Angeles). For more information, see List of tz database time zones.
  Create Subscription
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
  - 7
  - 8
  - 9
  - 10
  - 11
  - 12
  - 13
  - 14
  - 15
  - 16
  - 17
  - 18
  - 19
```
curl https://connect.squareupsandbox.com/v2/subscriptions \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "location_id": "{LOCATION_ID}",
    "plan_id": "{PLAN_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "card_id": "{CARD_ID}",
    "start_date": "{YYYY-MM-DD}",
    "tax_percentage": "5",
    "price_override_money": {
      "amount": 500,
      "currency": "USD"
    },
    "timezone": "America/Los_Angeles"
  }'
```
  Try in API Explorer
  The following is an example response:
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
  - 7
  - 8
  - 9
  - 10
  - 11
  - 12
  - 13
  - 14
  - 15
  - 16
  - 17
  - 18
  - 19
```
{
   "subscription":{
      "id":"b1f4c82c-1a61-4b80-9ec3-b542fdc11111",
      "location_id":"S8GWD5R9QB376",
      "plan_id":"3ZODVTLGZVTS6PGBY525H4HQ",
      "customer_id":"X09BC00N4WW277H37VKQJJ3GF8",
      "start_date":"2020-09-01",
      "status":"PENDING",
      "tax_percentage":"5",
      "price_override_money":{
         "amount":500,
         "currency":"USD"
      },
      "version":1596557314169,
      "created_at":"2020-08-04T16:08:34Z",
      "card_id":"ccof:OBdYpQWm8RGByBx93GB",
      "timezone":"America/Los_Angeles"
   }
}
```
  The response shows the subscription_status as PENDING. When the start date arrives, the status changes to ACTIVE. Square charges the card on file based on the subscription plan and sends an invoice receipt to the customer's email address. For example, if the subscription plan offers an initial free phase, the customer is billed (invoiced or charged) only after the free phase.
  The amount charged for this subscription is $5.25, which is the price override amount plus the 5% tax the example uses.
  
  Note
  
  Application fees, as currently supported in the Payments API, are not supported in the Subscriptions API and desirable fees should be negotiated with the seller and included in the subscription price to be presented to the user.
Example 3: Create subscriptions with an explicit source name.
A subscription can be created using Seller Dashboard, Square Point of Sales, or an application using the Subscription API. The resulting subscription has a source name to indicate what tool it was created with.
For example, if you use the Square API Explorer with the credentials of one of your Square applications, the default source name of the created subscription is the name of the application registered with the Square Developer Dashboard.
When creating a subscription using the API, you can explicitly specify a source name to override the default source name. This is useful to categorize your subscriptions by their sources of creation and then to facilitate querying for subscriptions by specified source names.
The following CreateSubscription example shows how to create a subscription with an explicit source name.
Create Subscription
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
```
curl https://connect.squareupsandbox.com/v2/subscriptions \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "location_id": "{LOCATION_ID}",
    "plan_id": "{PLAN_ID}",
    "customer_id": "{CUSTOMER_ID}",
    "source": {
      "name": "My iOS App"
    }
  }'
```
Try in API Explorer
An example response to this request is shows as follows:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
```
{
   "subscription": {
      "id": "375b45a4-16ef-48c7-ba5b-6368d0c42d95",
      "location_id": "SNTR5190QMFGM",
      "plan_id": "7UC3NMI7OJFGJJZTQLCZR5IW",
      "customer_id": "087HBRXVWCTY9046BZ1SW3M1RR",
      "start_date": "2021-10-20",
      "status": "ACTIVE",
      "version": 1,
      "created_at": "2021-10-20T12:51:26-07:00",
      "timezone": "America/Los_Angeles",
      "source": {
        "name": "My iOS App"
      }
   }
}
```
Suppose that you registered your Square application as "My Square App" and that you use this application's credentials to call the Square API. If you do not explicitly specify the source in the previous request, the response contains the registered Square application name as the default source name:
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
```
{
  {
      ...
      "source": {
        "name": "My Square App"
      }
   }
}
```
When an order is placed on a subscription, the subscription source name, if any, is propagated to the order's source name.

Link to section
Update subscriptions

You can modify or clear Subscription field values by calling UpdateSubscription. For example, use this endpoint to update the tax_percentage configured for a subscription, update a card_id on file, or clear an upcoming canceled_date.

In the request body, include the Subscription object with only the fields you want to update. To clear a field, set the field value to null.

Example 1: Update a subscription field. The following request updates the tax_percentage of the subscription, either by adding a new tax or updating the existing tax_percentage, if previously set:

Update Subscription

1
2
3
4
5
6
7
8
9
10

curl https://connect.squareupsandbox.com/v2/subscriptions/1ddfff2e-dc11-4473-80de-715ce11111 \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscription": {
      "tax_percentage": "3.2"
    }
  }'

Example 2: Update and clear subscription fields. The following request updates the price_override_money field and clears the tax_percentage and canceled_date fields:

Update Subscription

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

curl https://connect.squareupsandbox.com/v2/subscriptions/1ddfff2e-dc11-4473-80de-715ce11111 \
  -X PUT \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscription": {
      "price_override_money": {
        "amount": 2000,
        "currency": "USD"
      },
      "tax_percentage": null,
      "canceled_date": null
    }
  }'

The canceled_date of a subscription can only be removed to undo a future scheduled cancellation. Clearing the canceled_date field removes the pending cancellation from the subscription.

The following is an example response:

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

{
   "subscription":{
      "id":"1ddfff2e-dc11-4473-80de-715ce11111",
      "location_id":"S8GWD5R9QB376",
      "plan_id":"3ZODVTLGZVTS6PGBY525H4HQ",
      "customer_id":"7FCET7VZ0CTKZ6FXN6HXWVWNG0",
      "start_date":"2022-01-06",
      "charged_through_date":"2022-09-06",
      "status":"ACTIVE",
      "invoice_ids":[
         "inv:0-StJIz4N_4t7HXlLVckKyrw"
      ],
      "price_override_money":{
         "amount":2000,
         "currency":"USD"
      },
      "version":1596734520032,
      "created_at":"2022-01-06T17:06:48Z",
      "paid_until_date":"2022-09-06",
      "timezone":"UTC",
      "source": {
        "name": "My iOS App"
      }
    }
}

Because the tax_percentage and canceled_date fields are cleared, they are not returned in the response.

Link to section
Retrieve subscriptions

If you know the ID of a subscription to retrieve, call RetrieveSubscription and provide the subscription_id in the endpoint URL as shown:

Retrieve Subscription

curl https://connect.squareupsandbox.com/v2/subscriptions/b1f4c82c-1a61-4b80-9ec3-b542fdc11111 \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "subscription": {
    "id": "b1f4c82c-1a61-4b80-9ec3-b542fdc11111",
    "location_id": "S8GWD5R9QB376",
    "plan_id": "3ZODVTLGZVTS6PGBY525H4HQ",
    "customer_id": "X09BC00N4WW277H37VKQJJ3GF8",
    "start_date": "2020-09-01",
    "status": "PENDING",
    "price_override_money": {
      "amount": 500,
      "currency": "USD"
    },
    "version": 1596557579508,
    "created_at": "2020-08-04T16:08:34Z",
    "card_id": "ccof:OBdYpQWm8RGByBx93GB",
    "timezone": "America/Los_Angeles"
  }
}

Use the SearchSubscriptions endpoint to retrieve a list of all subscriptions. In addition, you can find subscriptions created at specific locations or optionally provide customer IDs to retrieve subscriptions purchased by a specific customer. These search results are grouped by location, within each location by customer, and then sorted in created_at order.

Search Subscriptions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

curl https://connect.squareupsandbox.com/v2/subscriptions/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "location_ids": [
          "lid_1",
          "lid_2",
          "lid_3"
        ],
        "customer_ids": [
          "cid_1",
          "cid_2",
          "cid_3"
        ]
      }
    }
  }'

In the response, you get the specified customer subscriptions associated with the locations specified. When working with a large number of Subscription objects, it might be helpful to paginate the response.

{"subscriptions": [
      {...},
      {...},
      {...},
 ]}

With the Square API 2021-10-20 or later, you can search for subscriptions by source name. To do so, set the source_names filter in the SearchSubscription request, as shown in the following code example:

Search Subscriptions

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl https://connect.squareupsandbox.com/v2/subscriptions/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "source_names": [
          "iOS App"
        ]
      }
    }
  }'

The response contains all subscriptions created with a source name matching "iOS App" as a substring. An example of such a response is shown as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
    "subscriptions": [
        {
            "id": "375b45a4-16ef-48c7-ba5b-6368d0c42d95",
            "location_id": "SNTR5190QMFGM",
            "plan_id": "7UC3NMI7OJFGJJZTQLCZR5IW",
            "customer_id": "087HBRXVWCTY9046BZ1SW3M1RR",
            "start_date": "2021-10-20",
            "charged_through_date": "2021-11-03",
            "status": "ACTIVE",
            "invoice_ids": [
                "inv:0-ChAZSa4MNoetfzG9DY4eU7CjENYO"
            ],
            "version": 1,
            "created_at": "2021-10-2012:51:26-07:00",
            "timezone": "America/Los_Angeles",
            "source": {
                "name": "My iOS App"
            }
        }
    ]
}

The same subscription is returned if the request's source_names filter contains a query string of "My iOS", "My", "iOS", or "App". However, the response does not contain this subscription if the query string is "My App". Notice that matching is case sensitive.

To view upcoming actions for each subscription in the response, set the include parameter to actions as shown:

Search Subscriptions

1
2
3
4
5
6
7
8
9
10

curl https://connect.squareupsandbox.com/v2/subscriptions/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "include": [
      "actions"
    ]
  }'

Link to section
Pause subscriptions

A subscription can be paused for a number of billing cycles without being canceled. Call PauseSubscription and include the id of the subscription to pause. Optionally, you can include a pause_reason and, if you know how long the subscription should be paused before being resumed, you can include either a pause_cycle_duration (the number of billing cycles to pause) or a resume_effective_date in the request. When called, a PAUSE action is scheduled and the subscription is paused at the end of the current billing period. At this time, the subscription's status is set to PAUSED.

For example, a gym might allow athletes to pause their monthly membership for up to 3 months in the event of an injury:

Pause Subscription

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/pause \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "pause_cycle_duration": 3,
    "pause_reason": "Injury"
  }'

The following is an example response:

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

{
 "subscription": {
   "id": "3d755d2e-bfc8-410c-822e-219f5c515cfe",
   "location_id": "LS41RG22G3RNG",
   "plan_id": "LOTN2MFIA57JWLRQEFLA2QDX",
   "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4",
   "start_date": "2021-09-30",
   "charged_through_date": "2021-10-30",
   "status": "ACTIVE",
   "invoice_ids": [
     "inv:0-ChDByALzpCEdISQ_YUcd3wfuEKsI"
   ],
   "version": 1,
   "created_at": "2021-09-30T20:32:45Z",
   "timezone": "UTC",
   "source": {
     "name": "my iOS App"
   }
 },
 "actions": [
   {
     "id": "99b2439e-63f7-3ad5-95f7-ab2447a80673",
     "type": "PAUSE",
     "effective_date": "2021-10-30"
   },
   {
     "id": "18ff74f4-3da4-30c5-929f-7d6fca84f115",
     "type": "RESUME",
     "effective_date": "2022-01-28"
   }
 ]
}

There are some restrictions on pausing a subscription:

Subscriptions cannot be paused during a free trial phase.
Subscriptions can be paused for any number of billing cycles within a single phase. For example, if a subscription has two billing cycles left in the current phase, it can be paused for up to two cycles only. If the pause_cycle_duration is set beyond the current phase, the request fails and the subscription is not paused.

Link to section
Resume subscriptions

To manually resume a paused or deactivated subscription, call ResumeSubscription with the desired subscription ID, resume_effective_date, and resume_change_timing to indicate whether the subscription should resume immediately on the resume_effective_date or at the end of the billing cycle for that date.

Prior to version 2021-11-17, ResumeSubscription was only used to resume deactivated subscriptions and only required a subscription_id. Now the endpoint has expanded to allow resuming paused subscriptions as well.

Resume Subscription

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/resume \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "resume_change_timing": "IMMEDIATE",
    "resume_effective_date": "2021-12-03"
  }'

The following is an example response:

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

{
 "subscription": {
   "id": "48f65b20-991b-4fb0-b312-66dad7207b16",
   "location_id": "LS41RG22G3RNG",
   "plan_id": "LOTN2MFIA57JWLRQEFLA2QDX",
   "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4",
   "start_date": "2021-09-30",
   "charged_through_date": "2021-10-30",
   "status": "PAUSED",
   "invoice_ids": [
     "inv:0-ChCtK-IEx5dSky0gP_ylQ6ZCEKsI"
   ],
   "version": 1,
   "created_at": "2021-09-30T20:30:59Z",
   "timezone": "UTC",
   "source": {
     "name": "My iOS App"
   }
 },
 "actions": [
   {
     "id": "18ff74f4-3da4-30c5-929f-7d6fca84f115",
     "type": "RESUME",
     "effective_date": "2021-12-03"
   }
 ]
}

When called, a RESUME action is scheduled. Note that if a RESUME action is already scheduled, you must first cancel the pending action and then call ResumeSubscription to schedule a new one.

Link to section
Cancel subscriptions

When you cancel a subscription, the canceled_date field is set to the end of the active billing cycle and a CANCEL action is scheduled for the same date. After this date, the status changes from ACTIVE to CANCELED. For example, if the subscription is in a phase with a monthly cadence, the canceled_date is set depending on when the phase started:

If the phase started on the first of the month, the canceled_date is set to the end of the month.
If the phase started on March 5, the canceled_date is set to April 5.

Cancel Subscription

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/cancel \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response. The subscription_status remains ACTIVE; however, the canceled_date is set to end of the current billing period.

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

  {
  "subscription": {
    "id": "8d17e86c-057e-41c4-b4be-783e94ac4d7a",
    "location_id": "LS41RG22G3RNG",
    "plan_id": "LOTN2MFIA57JWLRQEFLA2QDX",
    "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4",
    "start_date": "2021-09-30",
    "canceled_date": "2021-11-29",
    "charged_through_date": "2021-11-29",
    "status": "ACTIVE",
    "invoice_ids": [
      "inv:0-ChB6OFDf3lO1jAXecZ_u4vT_EKsI",
      "inv:0-ChBjEJT6X2XV0D06PbGl8H-TEKsI"
    ],
    "version": 1,
    "created_at": "2021-09-30T20:36:24Z",
    "timezone": "UTC",
    "source": {
      "name": "My iOS App"
    }
  },
  "actions": [
    {
      "id": "10aec353-53f9-3409-aa71-c38654c3d402",
      "type": "CANCEL",
      "effective_date": "2021-11-29"
    }
  ]
}

Link to section
Swap subscription plans

You can swap the subscription plan associated with a customer. For example, to upgrade a customer to a new premium plan or change a plan without altering the original plan for other subscribers. To do so, call the SwapPlan endpoint, including the subscription_id to update in the path and the new_plan_id in the request body as shown:

Swap Plan

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/swap-plan \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "new_plan_id": "6MXKHZTCHMPCSRJMIQB75U6"
  }'

SwapPlan replaces the original plan with the new subscription plan at the end of the current billing cycle. This means that the original plan is still in effective until the end of the current billing cycle. When SwapPlan is called and the start of the new plan is pending, the subscription has a SWAP_PLAN action associated with it.

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

{
  "subscription": {
    "id": "5e030152-82b1-43dc-9f96-ec069d71d542",
    "location_id": "LS41RG22G3RNG",
    "plan_id": "LOTN2MFIA57JWLRQEFLA2QDX",
    "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4",
    "start_date": "2021-09-30",
    "charged_through_date": "2021-11-29",
    "status": "ACTIVE",
    "invoice_ids": [
      "inv:0-ChBUOfkUkKfuqLIf9Gy4Qy-qEKsI",
      "inv:0-ChBnNZYwIhhLZ7pm2cd2PJPrEKsI"
    ],
    "version": 1,
    "created_at": "2021-09-30T20:34:48Z",
    "timezone": "UTC",
    "source": {
      "name": "Sandbox for sq0ids-AJhvDCw3KCZ4pTqxHrr5uQ"
    }
  },
  "actions": [
    {
      "id": "f0a1dfdc-675b-3a14-a640-99f7ac1cee83",
      "type": "SWAP_PLAN",
      "effective_date": "2021-11-29",
      "new_plan_id": "6MXKHZTCHMPCSRJMIQB75U6"
    }
  ]
}

Link to section
Subscription price override

For a gym membership subscription plan, you might offer a 50% off summer special. Subscriptions created during this period override the plan price by adding price_override_money in the request.
A subscription plan created for charitable causes might offer free subscriptions, hoping that subscribers give donations. These subscribers can set the price for their subscriptions.

In these cases, the price_override_money field is set on the individual subscription. This price override does not apply to the free-trial phase in a subscription (see About the free-trial phase in a plan).

The price_override_money overrides the recurring_price_money of all the subscription phases (except the initial free-trial phase, if present) regardless of the phase cadence.

When setting the subscription price override, see the related Requirements and limitations.

Link to section
Example 1

Consider a gym membership subscription plan defined as having two phases:

Phase 1: Six-week free membership. For this phase, the cadence is weekly, recurring_price_money is 0, and period is 6.
Phase 2: A monthly price of $60, after the initial phase. For this phase, cadence is monthly, recurring_price_money is $60, and you do not specify the period (to indicate the never ending phase).

Now suppose you offer a 50% summer special for gym memberships. For subscriptions created during the summer, you include price_override_money in the CreateSubscription request and set it to $30.

Phase 1: The price has no effect. It remains a free phase.
Phase 2: The monthly price changes to $30.

Link to section
Example 2

Consider another fictitious subscription plan defined as having two phases:

Phase 1: A one-year phase price at $500. For this phase, the cadence is yearly, recurring_price_money is $500, and period is 1.
Phase 2: A monthly price of $50, after the initial phase. For this phase, cadence is monthly, recurring_price_money is $50, and you do not specify the period (to indicate the never ending phase).

Now suppose you create a subscription that specifies price_override_money of $1 in the CreateSubscription request:

Phase 1: The price changes to $1 (for the entire year).
Phase 2: The price also changes to $1 (monthly).

The price_override_money applies to all phases (except the initial free phase, if any) regardless of the phase cadence (monthly and yearly, in this example).

Link to section
Example 3

Consider another fictitious subscription plan for charitable causes, where the subscribers specify the amount they want to donate every year.

In this case, you define a plan as having one phase with the yearly price set at $0. Because this plan has only one phase, even though the price is $0, it is not a free-trial phase (see About the free-trial phase in a plan). So when you create a subscription that specifies price_override_money (for example, a $10 donation every year), the phase price changes to $10 per year.

Link to section
Requirements and limitations

The minimum amount you can charge for a subscription is $1. A subscription can have a free trial which you indicate by setting a $0 price for the first phase. You configure the subscription price in two places:
- On the subscription plan. For more information, see Set up a subscription plan.
- With a subscription price override. For more information, see Subscription object.
ACH payments are not possible through the Subscriptions API because bank account sources cannot be stored on file and charged later.
For OAuth flow, the Subscriptions API requires OAuth credentials and permissions. For more information about credentials, see Square API Access Tokens. In addition, the Subscriptions API requires these permissions:
SUBSCRIPTIONS_READ and SUBSCRIPTIONS_WRITE.
ORDERS_READandORDERS_WRITE.These permissions are required to create invoices.
PAYMENTS_READandPAYMENTS_WRITE. When you charge a card on file for the subscription, these permissions are required.
CUSTOMERS_READ. The subscription is associated with a customer profile in the seller's Customer Directory. Therefore, to create or manage subscriptions, you need this permission.

Link to section
Webhooks

A webhook is a subscription that notifies you when a Square event occurs. For more information about using webhooks, see Square Webhooks Overview.

The Subscriptions API uses the following webhook events:

Event	Permission	Description
subscription.created	`SUBSCRIPTIONS_READ`	A `Subscription` object was created.
subscription.updated	`SUBSCRIPTIONS_READ`	A `Subscription` object was updated.

For a complete list of webhook events, see V2 Webhook Events Reference.

Link to section
Additional considerations

The following sections provide additional information.

Link to section
Subscription billing and invoices

Square bills the subscriptions in advance. At the start of a billing period, customers receive an emailed invoice, or if there is a card_id on file, the card is automatically charged. The billing cycle starts on the subscription start date and repeats per the plan cadence (see Set up and Manage a Subscription Plan.

For a plan with a monthly cadence (including multiple months, such as every three months), if the billing date is after the end of a given month, Square bills the subscription on the last day of that month. For example, if the subscription starts on May 31, Square sends the next bill on June 30.

In addition, note the following:

If a subscription has a card_id set and Square's attempt to charge the card fails, Square sends the invoice to the customer's email address with a link to follow for making a payment.
Square does not receive complete information from credit card providers about why payments fail. Therefore, if a customer's card fails or is declined, they should reach out to the card provider for more information.
As long as the subscription is active, Square sends invoices regardless of whether the customer paid the invoices previously billed. Each invoice amount remains specific to the billing period (individual invoices do not show any accumulation of the outstanding balance).
Both the customer and seller receive emails for each invoice billed. The email includes a URL to Square-hosted invoice page for the customer to pay the invoice. If Square charged the customer's card on file, the email provides the receipt.
All invoices that the Subscriptions API creates are available in the Seller Dashboard. You can also use the Invoices API to manage them. For more information, see Invoices API Overview. Invoices that are created by the Subscriptions API include a subscription_id field.
Subscription payment status can be tracked by subscribing to the payment_made webhook event of the Invoices API or by calling the ListPayments or GetPayment endpoint of the Payments API to retrieve payment objects and inspect the payment status.
Subscription payments incur seller transaction fees , as do all card payments made through Square APIs. These fees vary by country.
Under specific conditions, Square might deactivate a subscription. For more information, see Deactivated subscriptions.

Link to section
Subscription actions

Actions are scheduled, future changes to subscriptions. When calling RetrieveSubscription or SearchSubscriptions, you can set the include query parameter to actions as shown to include the actions associated with the subscription in the response:

Retrieve Subscription

curl https://connect.squareupsandbox.com/v2/subscriptions/b1f4c82c-1a61-4b80-9ec3-b542fdc11111 \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

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

{
  "subscription": {
    "id": "8cb3cc07-b408-4340-a528-c2b971161e89",
    "location_id": "LS41RG22G3RNG",
    "plan_id": "LOTN2MFIA57JWLRQEFLA2QDX",
    "customer_id": "NC634K4Q2CZF19ZVZ9731WQ5A4",
    "start_date": "2021-09-30",
    "charged_through_date": "2021-10-30",
    "status": "ACTIVE",
    "invoice_ids": [
      "inv:0-ChBV_wzLxkOMfFM1CRi-pJ0QEKsI"
    ],
    "version": 1,
    "created_at": "2021-09-30T20:35:21Z",
    "timezone": "UTC",
    "source": {
      "name": "My iOS App"
    },
    "actions": [
      {
        "id": "f0a1dfdc-675b-3a14-a640-99f7ac1cee83",
        "type": "SWAP_PLAN",
        "effective_date": "2021-10-30",
        "new_plan_id": "P6MXKHZTCHMPCSRJMIQB75U6"
      },
      {
        "id": "99b2439e-63f7-3ad5-95f7-ab2447a80673",
        "type": "PAUSE",
        "effective_date": "2021-12-29"
      },
      {
        "id": "18ff74f4-3da4-30c5-929f-7d6fca84f115",
        "type": "RESUME",
        "effective_date": "2022-01-28"
      }
    ]
  }
}

The possible actions associated with subscriptions are PAUSE, RESUME, SWAP_PLAN, and CANCEL. These actions can be scheduled by calling PauseSubscription, ResumeSubscription, SwapSubscription, or CancelSubscription, respectively.

When the action occurs, it becomes an event and can be accessed by calling ListSubscriptionEvents.

Link to section
Cancel an action

If you want to cancel an action before it occurs (for example, if a PAUSE action had been scheduled but is no longer necessary), call DeleteSubscriptionAction with the subscription_id and action_id to cancel.

Delete Subscription Action

curl https://connect.squareupsandbox.com/v2/subscriptions/%7BSUBSCRIPTION_ID%7D/actions/%7BACTION_ID%7D \
  -X DELETE \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Link to section
Subscription events

Events represent past subscription changes. Use ListSubscriptionEvents to retrieve events for a subscription. The events associated with subscriptions are START_SUBSCRIPTION, STOP_SUBSCRIPTION (when the subscription is canceled), PLAN_CHANGE (swapping subscriptions), RESUME_SUBSCRIPTION, PAUSE_SUBSCRIPTION, and DEACTIVATE_SUBSCRIPTION. You provide the subscription ID in the endpoint URL as shown:

List Subscription Events

curl https://connect.squareupsandbox.com/v2/subscriptions/{subscription_id}/events \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "subscription_events": [
    {
      "id": "884b0d09-112b-4eae-929e-1154f0b5ccd1",
      "subscription_event_type": "START_SUBSCRIPTION",
      "effective_date": "2021-02-28",
      "plan_id": "RN3E4TBOBPDWHLB2OXG5VLYS"
    },
    {
      "id": "fd7d97f3-beba-4762-8d6f-f408aa1d96d1",
      "subscription_event_type": "PAUSE_SUBSCRIPTION",
      "effective_date": "2021-05-28",
      "plan_id": "RN3E4TBOBPDWHLB2OXG5VLYS"
    },
    {
      "id": "d7e9db43-3595-4f93-adb5-a5ab88c79c71",
      "subscription_event_type": "RESUME_SUBSCRIPTION",
      "effective_date": "2021-08-28",
      "plan_id": "RN3E4TBOBPDWHLB2OXG5VLYS"
    }
  ]
}

Link to section
Deactivated subscriptions

After a subscription is created, there are events that can make a subscription non-billable, causing Square to deactivate the subscription. Some of the reasons include:

The customer's email address is deleted from the profile in the seller's Customer Directory.
The customer's email is no longer valid in the profile in the seller's Customer Directory.
The customer's name is deleted from the profile in the seller's Customer Directory.
The location is deactivated by the seller.
The location is not allowed to accept payments by the Square risk department.

Customer profile deletion is an irreversible action. Therefore, if a customer profile is deleted, Square cancels the subscription.

The following is an example subscription with the status set to DEACTIVATED.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

{
  "subscription": {
    "id": "337270b4-2154-49a0-8160-710dd05930a7",
    "location_id": "7WQ0KXC8ZSD90",
    "plan_id": "DYTUGVCCDBZRQDP3ASBBTPYL",
    "customer_id": "VXWW1WCNWCVDDBM0VGF3XJV9H8",
    "start_date": "2021-03-18",
    "charged_through_date": "2021-03-20",
    "status": "DEACTIVATED",  
    "invoice_ids": [
      "inv:0-ChDqhmIo-6qI0lpT567p1_XtEJAH"
    ],
    "version": 1616085625242,
    "created_at": "2021-03-18T09:40:25-07:00",
    "paid_until_date": "2021-03-20",
    "timezone": "America/Los_Angeles"
  }
}

Note that Square deactivates a subscription only at the end of the billing cycle. For example, consider a monthly billing cycle starting on the first day of the month. Now consider the following example sequence:

On January 1, a monthly subscription is created for a customer.
On January 15, the customer's email is deleted.
On February 1, Square discovers that the subscription is non-billable and deactivates the subscription. Square does not send any new invoices.

Applications can subscribe to the subscription.updated webhook to receive subscription deactivation notifications (when the subscription's status changes to DEACTIVATED). A seller can also use the Seller Dashboard to find deactivated subscriptions.

There are two ways to resume a deactivated subscription:

A seller can resume a deactivated subscription in the Seller Dashboard.
If subscriptions are managed programmatically, applications can call ResumeSubscription as shown:
- 1
- 2
- 3
- 4
- 5
```
curl https://connect.squareupsandbox.com/v2/subscriptions/{SUBSCRIPTION_ID}/resume \
  -H 'Square-Version: 2021-04-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -X POST
```
ResumeSubscription sets the subscription status to ACTIVE.
The resumption of a deactivated subscription fails unless all issues are resolved.

After a subscription is resumed in the middle of the billing cycle, Square sends a prorated invoice for the remaining billing cycle. For example, consider a monthly billing cycle starting on the first day of the month. Now consider the following example sequence:

On January 1, a subscription is created for a customer.
On January 15, the customer's email was deleted.
On February 1, Square discovers that the subscription is non-billable and deactivates the subscription.
On February 15, the customer's email is added back to the profile.
On February 15, the application called ResumeSubscription.
On February 15, Square sends a prorated invoice for the rest of February.

Applications can call ListSubscriptionEvents as shown to determine why a subscription was deactivated by Square.

curl https://connect.squareupsandbox.com/v2/subscriptions/{SUBSCRIPTION_ID}/events \
  -H 'Square-Version: 2021-04-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following is an example response. It shows a list of events, one of which is an event of the type DEACTIVATE_SUBSCRIPTION. The info object provides the reason code and details why the subscription was deactivated.

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

  {
  "subscription_events": [
    {
      "id": "428cdeaf-71f6-46e3-87ee-e2954c1b01b8",
      "subscription_event_type": "START_SUBSCRIPTION",
      "effective_date": "2021-03-18",
      "plan_id": "DYTUGVCCDBZRQDP3ASBBTPYL"
    },
    {
      "id": "f195d3e3-b71b-4adf-a8ac-1279781c8614",
      "subscription_event_type": "DEACTIVATE_SUBSCRIPTION",
      "effective_date": "2021-03-19",
      "plan_id": "DYTUGVCCDBZRQDP3ASBBTPYL",
      "info": {
        "detail": "The customer with ID `PT7KZ4P8A0SZ75P8GAN30E06BM` does not have an email address.",
        "code": "CUSTOMER_NO_EMAIL"
      }
    },
    {
      "id": "0e631bca-caea-442e-96c8-0260db65542c",
      "subscription_event_type": "RESUME_SUBSCRIPTION",
      "effective_date": "2021-03-20",
      "plan_id": "DYTUGVCCDBZRQDP3ASBBTPYL"
    }
  ]
}

Link to section
Related topics

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Manage Subscriptions Using the Subscriptions API

On this page

On this page

Link to section
Subscription object

Note

Link to section
Manage enrollments in a subscription plan

Link to section
Create subscriptions

Note

Note

Link to section
Update subscriptions

Note

Link to section
Retrieve subscriptions

Link to section
Pause subscriptions

Link to section
Resume subscriptions

Link to section
Cancel subscriptions

Link to section
Swap subscription plans

Link to section
Subscription price override

Important

Link to section
Example 1

Link to section
Example 2

Link to section
Example 3

Link to section
Requirements and limitations

Link to section
Webhooks

Link to section
Additional considerations

Link to section
Subscription billing and invoices

Link to section
Subscription actions

Link to section
Cancel an action

Link to section
Subscription events

Link to section
Deactivated subscriptions

Note

Link to section
Related topics

On this page

Docs

Manage Subscriptions Using the Subscriptions API

On this page

On this page

Link to section Subscription object

Note

Link to section Manage enrollments in a subscription plan

Link to section Create subscriptions

Note

Note

Link to section Update subscriptions

Note

Link to section Retrieve subscriptions

Link to section Pause subscriptions

Link to section Resume subscriptions

Link to section Cancel subscriptions

Link to section Swap subscription plans

Link to section Subscription price override

Important

Link to section Example 1

Link to section Example 2

Link to section Example 3

Link to section Requirements and limitations

Link to section Webhooks

Link to section Additional considerations

Link to section Subscription billing and invoices

Link to section Subscription actions

Link to section Cancel an action

Link to section Subscription events

Link to section Deactivated subscriptions

Note

Link to section Related topics

On this page

Link to section
Subscription object

Link to section
Manage enrollments in a subscription plan

Link to section
Create subscriptions

Link to section
Update subscriptions

Link to section
Retrieve subscriptions

Link to section
Pause subscriptions

Link to section
Resume subscriptions

Link to section
Cancel subscriptions

Link to section
Swap subscription plans

Link to section
Subscription price override

Link to section
Example 1

Link to section
Example 2

Link to section
Example 3

Link to section
Requirements and limitations

Link to section
Webhooks

Link to section
Additional considerations

Link to section
Subscription billing and invoices

Link to section
Subscription actions

Link to section
Cancel an action

Link to section
Subscription events

Link to section
Deactivated subscriptions

Link to section
Related topics