Subscriptions API Overview

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 - 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.
Link to section

Requirements and limitations

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

Link to section

Webhooks

The Subscriptions API supports the following webhook events:

EventPermissionDescription
subscription.createdSUBSCRIPTIONS_READA Subscription object was created.
subscription.updatedSUBSCRIPTIONS_READA 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:

EventPermissionDescription
invoice.publishedINVOICES_READAn invoice was published. All invoices created by the Subscriptions API include a subscription_id field.
invoice.payment_madeINVOICES_READA payment was made for an invoice.
order.createdORDERS_READAn order was created.
order.updatedORDERS_READAn order was updated.
payment.updatedPAYMENTS_READA 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.