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:
- Create a subscription plan using the Catalog API, configuring the items or categories available for subscription.
- Create a subscription plan variation using the Catalog API, configuring the billing periods, pricing information, discounts, and subscription availability.
- (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.
- 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
andSUBSCRIPTIONS_WRITE
.ORDERS_READ
andORDERS_WRITE
.ITEMS_READ
. Required for creating itemized subscriptions.INVOICES_WRITE
. Required for creating invoices.PAYMENTS_READ
andPAYMENTS_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:
Event | Permission | Description |
---|---|---|
subscription.created | SUBSCRIPTIONS_READ | A Subscription object was created. |
subscription.updated | SUBSCRIPTIONS_READ | A Subscription object was updated. |
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:
Event | Permission | Description |
---|---|---|
invoice.published | INVOICES_READ | An invoice was published. All invoices created by the Subscriptions API include a subscription_id field. |
invoice.payment_made | INVOICES_READ | A payment was made for an invoice. |
order.created | ORDERS_READ | An order was created. |
order.updated | ORDERS_READ | An order was updated. |
payment.updated | PAYMENTS_READ | A payment was updated. To determine if a subscription charge failed, listen for this webhook and filter for payments where the status is FAILED . |
For a complete list of webhook events, see V2 Webhook Events Reference.