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.
- 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
SubscriptionPlanVariationwith 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:
ITEMS_READ. Required for creating itemized subscriptions.
INVOICES_WRITE. Required for creating invoices.
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:
|invoice.published||An invoice was published. All invoices created by the Subscriptions API include a |
|invoice.payment_made||A payment was made for an invoice.|
|order.created||An order was created.|
|order.updated||An order was updated.|
|payment.updated||A payment was updated. To determine if a subscription charge failed, listen for this webhook and filter for payments where the |
For a complete list of webhook events, see V2 Webhook Events Reference.