Subscriptions API

Applies to: Subscriptions API | Catalog API | Orders API | Invoices API

Learn about using the Subscriptions API to create and manage subscriptions in a subscription plan.

Square 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 - 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 - Represents how the product is being sold; that is, how often and for what price.
• Subscription - 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_READ and 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.

Depending on its functionality, your application might also require other Square permissions. For more information, see OAuth API.

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 Webhook Events Reference.