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

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.
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 example:
- For a gym membership subscription plan, you might offer a 50% off summer special. Subscriptions created during this period override the plan price.
- A subscription plan created for charitable causes might offer free subscription hoping for members who subscribe to give donations. These subscribers can set the price for their subscriptions.
  In these cases, the price_override_money field is set on the subscription. This price override does not apply to free trial subscription phases.
When setting the subscription price override, see the related Requirements and Limitations .
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.

Manage enrollments in a subscription plan

You use the Subscriptions API to create and manage subscriptions.

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, Manage Customers and Integrate With Other Services).

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:

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

The following is an example response:

{
"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 Subscriptions Walkthrough.

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.
```
curl -X POST \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Accept: application/json' \
-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"
}' \
'https://connect.squareupsandbox.com/v2/subscriptions'  
```
  The following is an example response:
```
{
   "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.

Update subscriptions

You call UpdateSubscription to update a subscription. You can modify subscription field values, clear field values, or do both. For example:

The seller might want to update the tax percentage configured for a subscription.
Suppose a subscription has a cancellation date set. Now the customer decides to continue the subscription. In this case, you want to clear the canceled_date field.

The request body must include the subscription object with the version and fields to update. To clear a field, set the field value to null.

The UpdateSubscription requires a version and it must match the current subscription version. If you do not know the version, call GetSubscription or ListSubscriptions. The following are example UpdateSubscription requests:

Example 1: Update a subscription field. The following UpdateSubscription request sets the subscription tax percentage:
```
curl -X PUT \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "subscription": {
    "version":1589941853858,
    "tax_percentage":"5"
  }
}
' \
'https://connect.squareupsandbox.com/v2/subscriptions/{{SUBSCRIPTION_ID}}'
```
This request either adds a tax percentage or updates an existing tax percentage, if previously set.

Note

You can associate a subscription with a different subscription plan by updating the plan ID. When you do this, the subscription behaves as if it was created with the new plan from the beginning. For example, if a subscription was in the 15th day (since creation) in the original plan, it remains in the 15th day in the new plan (whatever phase that might be in the new plan). The pricing for the new plan goes in effect in the next billing cycle.

Example 2: Update and clear subscription fields. The following UpdateSubscription request updates a field (price_override_money) and clears two fields (tax_percentage and canceled_date).

curl -X PUT \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
   "subscription":{
      "version": {{VERSION}},
      "price_override_money":{
         "amount":2000,
         "currency":"USD"
      },
      "tax_percentage": null,
      "canceled_date": null
   }
}' \
'https://connect.squareupsandbox.com/v2/subscriptions/{{SUBSCRIPTION_ID}}'

Clearing the canceled_date field removes the pending cancellation from the subscription. The following is an example response:

{
   "subscription":{
      "id":"1ddfff2e-dc11-4473-80de-715ce11111",
      "location_id":"S8GWD5R9QB376",
      "plan_id":"3ZODVTLGZVTS6PGBY525H4HQ",
      "customer_id":"7FCET7VZ0CTKZ6FXN6HXWVWNG0",
      "start_date":"2020-08-06",
      "charged_through_date":"2020-09-06",
      "status":"ACTIVE",
      "invoice_ids":[
         "StJIz4N_4t7HXlLVckKyrw"
      ],
      "price_override_money":{
         "amount":2000,
         "currency":"USD"
      },
      "version":1596734520032,
      "created_at":"2020-08-06T17:06:48Z",
      "paid_until_date":"2020-09-06",
      "timezone":"Etc/UTC"
   }
}

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

Retrieve subscriptions

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

curl -X GET \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
'https://connect.squareupsandbox.com/v2/subscriptions/{{SUBSCRIPTION_ID}}'

The following is an example response:

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

You can use the SearchSubscriptions endpoint to find subscriptions created at specific locations. In addition, you can optionally provide customer IDs to retrieve customer subscriptions created at the specified locations. The search results are grouped by location, within each location by customer, and then sorted in created_at order.

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

In the response, you get the specified customer subscriptions associated with the location specified:

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

You can optionally specify limit in the request body to limit the number of subscriptions returned in the response:

...
-d '{
    "query": {
      "filter": {
        "location_ids": ["lid_1", "lid_2", "lid_3"],
        "customer_ids": ["cid_1", "cid_2", "cid_3"]
      },
   "limit": 20
}'
...

If the response is truncated (there are more subscriptions to return), it includes a cursor:

{
  "subscriptions": [
      {...},
      {...},
      {...},
  ],
   "cursor": "Cg1FWkhHSjdTTlZBSjE5GAI="
}

You specify this cursor in the body of the next request to retrieve the next set of subscriptions:

...
-d '{
    "query": {
      "filter": {
         "location_ids": ["EZHGJ7EXAMPLE"]
      }
 "limit": 2,
 "cursor": "Cg1FWkhHSjdTTlZBSjE5GAI="
}'
...

Cancel subscriptions

When you cancel a subscription, the canceled_date field is set to the end of the active billing period. 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.

curl -X POST \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
  'https://connect.squareupsandbox.com/v2/subscriptions/{{SUBSCRIPTION_ID}}/cancel'

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

{
   "subscription":{
      "id":"b1f4c82c-1a61-4b80-9ec3-b542fdc11111",
      "location_id":"S8GWD5R9QB376",
      "plan_id":"3ZODVTLGZVTS6PGBY525H4HQ",
      "customer_id":"X09BC00N4WW277H37VKQJJ3GF8",
      "start_date":"2020-09-01",
      "canceled_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"
   }
}

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

Webhooks

The Subscriptions API supports webhook notifications. For a list subscription events you can subscribe to, see Subscribe to Events.

Additional considerations

The following sections provide additional information:

Subscription billing

Square bills the subscriptions in advance. That is, customers get a bill (receive an invoice by email or their card is automatically charged) at the beginning of the billing period. The billing cycle starts on the subscription start date and repeats per the plan cadence (see Square Subscriptions).

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

Manage subscription invoices

After creating a subscription, Square bills the customer, either by sending an invoice to the customers email address or charging a card on file if provided in the CreatePayment request. The billing occurs per the subscription plan cadence (see Square Subscriptions). 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 Manage Invoices Using the Invoices API.

Subscription events

Use ListSubscriptionEvents to retrieve events for a subscription. In the current implementation, only START_SUBSCRIPTION and STOP_SUBSCRIPTION (when the subscription was canceled) events are returned. You provide the subscription ID in the endpoint URL as shown:

curl -X GET \
-H 'Authorization: Bearer {{{ACCESS_TOKEN}}}' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
'https://connect.squareupsandbox.com/v2/subscriptions/{{SUBSCRIPTION_ID}}/events'

The following is an example response:

{
  "subscription_events": [
    {
      "subscription_event_id": "645c019f-8a18-41b6-87ae-85555EXAM PLE",
      "subscription_event_type": "START_SUBSCRIPTION",
      "effective_date": "2020-04-24",
      "plan_id": "AFW3O3KPLRPQJQWW7EXAMPLE"
    },
    {
      "subscription_event_id": "92e907e6-6ddf-4c93-87cc-67cb8EXAMPLE",
      "subscription_event_type": "STOP_SUBSCRIPTION",
      "effective_date": "2020-05-06",
      "plan_id": "AFW3O3KPLRPQJQWW7EXAMPLE"
    }
  ]
}

Manage Subscriptions Using the Subscriptions API

On this page

Subscription object

Note

Manage enrollments in a subscription plan

Create subscriptions

Note

Update subscriptions

Note

Retrieve subscriptions

Cancel subscriptions

Requirements and limitations

Webhooks

Additional considerations

Subscription billing

Manage subscription invoices

Subscription events

Related topics

Still haven't found what you are looking for?

Manage Subscriptions Using the Subscriptions API

On this page

Subscription object Permalink Get a link to this section

Note

Manage enrollments in a subscription plan Permalink Get a link to this section

Create subscriptions Permalink Get a link to this section

Note

Update subscriptions Permalink Get a link to this section

Note

Retrieve subscriptions Permalink Get a link to this section

Cancel subscriptions Permalink Get a link to this section

Requirements and limitations Permalink Get a link to this section

Webhooks Permalink Get a link to this section

Additional considerations Permalink Get a link to this section

Subscription billing Permalink Get a link to this section

Manage subscription invoices Permalink Get a link to this section

Subscription events 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?

Subscription object

Manage enrollments in a subscription plan

Create subscriptions

Update subscriptions

Retrieve subscriptions

Cancel subscriptions

Requirements and limitations

Webhooks

Additional considerations

Subscription billing

Manage subscription invoices

Subscription events

Related topics