Subscriptions API Overview

Subscriptions allow sellers to generate recurring revenue by offering a scheduled fulfillment of products or services. For example, a shop might offer customers the ability to receive an item or set of items on a weekly or monthly basis. Multiple subscription options can enable customers to select different tiers and customize the frequency of their subscription. Basically, subscriptions represent recurring orders billed to customers on a specified cadence.

A recurring subscription is represented by three parts in the Square API data model:

• Subscription plan - This represents what is being sold. This can be a single item, a series of recurring services, or a category of items or services.
• Subscription plan variation - This represents how the product is being sold; that is, how often and for what price.
• Subscription - This represents who is buying the product or service. It's an agreement with a specific customer to purchase a subscription from the business.

Subscriptions work with the Catalog API, Orders API, Invoice objects, Customer objects, and Discount objects. The high-level steps of working with subscriptions are:

1. Create a subscription plan using the Catalog API, configuring the items or categories available for subscription.
2. Create a subscription plan variation using the Catalog API, configuring the billing periods, pricing information, discounts, and subscription availability.
3. (Optional) If your subscription involves the sale of items in a Square catalog, create order templates with the Orders API to represent a Square order to be fulfilled on a recurring basis.
4. Create a subscription with the Subscriptions API to represent a customer's enrollment in a subscription.

• Catalog items sold through subscriptions must be shipped to the customer. Subscription items aren't yet available for in-person pickup.
• The minimum amount you can charge for a subscription is $1. A subscription can have a free trial period, which is established by setting an initial phase on a SubscriptionPlanVariation with a 100% discount.
• ACH payments aren't available through the Subscriptions API because bank account sources cannot be stored on file and charged later.
• The Subscriptions API requires the following OAuth permissions:
  • SUBSCRIPTIONS_READ and SUBSCRIPTIONS_WRITE.
  • ORDERS_READ and ORDERS_WRITE.
  • ITEMS_READ. Required for creating itemized subscriptions.
  • INVOICES_WRITE. Required for creating invoices.
  • PAYMENTS_READ and PAYMENTS_WRITE. Required for charging a card on file for the subscription.
  • CUSTOMERS_READ. Required to associate a subscription with a customer profile in the seller's Customer Directory.

Your application uses these permissions to manage invoices on behalf of a seller. Depending on its functionality, your application might also require other Square permissions. For more information, see OAuth API Overview.

The Subscriptions API supports the following webhook events:

Additionally, you might find it useful to subscribe to webhook events for other APIs that integrate with subscriptions, such as the events in the following table:

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