In the Square API data model, the Subscription object represents an agreement between a customer and a seller to make a payment on a set schedule. A subscription is associated with a particular customer using a customer_id and associated with a particular location using a location_id. Additionally, the
Subscription object contains many important fields, including:
- card_id - When you create a subscription, Square sends an invoice to the customer's email address. Optionally, a card on file can be linked with the subscription so that Square can charge the card and email a receipt for the invoice. ACH payments aren't possible through the Subscriptions API because bank account sources cannot be stored on file and charged later.
- start_date - By default, the subscription starts as soon as you create a subscription. You can optionally configure a start date to start the subscription some time in future. Initially, these subscriptions have a
ACTIVEon the start date.
- source - The name used to identify the place (physical or digital) that a subscription originates. By default, the source is the name of the application that created the subscription.
- plan_variation_id - The
SubscriptionPlanVariationto which this customer is subscribing.
- canceled_date - The
SubscriptionPlanVariationdictates if and when a subscription ends based on the number of periods in its final phase. You also have the option to call CancelSubscription to cancel a subscription. If you set the
canceled_date, the subscription cancels on the specified date and the final bill is prorated accordingly. However, if you call
CancelSubscription, the subscription cancels at the end of the current billing cycle.
- phases - If the
PlanVariationincludes any phases with the
RELATIVEpricing type, you must also include the same number of phases in the
Subscriptionobject. These phases must include ordinals that correspond to the same phases in the
order_template_idfor each included phase.
- invoice_ids - Each time an invoice is generated for a subscription, its ID is listed in this field, in the order of when the invoices were created (newest invoices appear first).
Each payment for a subscription represents the fulfillment of a Square order. Before a customer can purchase a subscription, there must be an existing order template (an order in DRAFT state) for each of the payment scenarios represented by a phase in the subscription. For example, consider a "Coffee of the Month Club"
- The first phase lasts a single month and has a static price of $10.
- The second phase is priced
RELATIVEto the item's price and contains the ID of an existing CatalogDiscount object, which takes 15% off the price of the purchased item.
To create order templates for this subscription, make two calls to CreateOrder, one for each
line_items should include the
catalog_object_id of the items being purchased, including any modifiers. If any
service_charges apply to the subscription phase, include them in the order template. The following example creates a template for an order of one bag of coffee with a 15% discount applied. To use this order as a subscription's order template, the order's
state must be set to
The response includes the entire
Order object. Take note of the
id. It's used in the following step when creating the
To learn more about working with orders, see Orders API Overview.
To enroll a customer in a subscription, call CreateSubscription. In the request, include the customer ID, plan variation ID, and a location ID to associate with the subscription. The customer ID refers to the customer profile in the seller's Customer Directory.
Example 1: Coffee of the Month Club
CreateSubscription request enrolls a customer in the "Coffee of the Month Club"
SubscriptionPlanVariation. Because one of the phases in the plan variation includes a pricing type of
RELATIVE, you must include phases in the
Subscription object as well. Each phase contains the ID for the order template corresponding to that phase.
The following response provides the
Note the following:
- The request doesn't specify a
card_idfor payment; therefore, Square sends the invoice to the customer's email address.
- The request doesn't specify
start_date; therefore, the subscription starts immediately.
- The subscription's
sourcename is the name of the application that created the subscription.
Example 2: Static price subscription with a delayed start
CreateSubscription request enrolls a customer in a "Friends of the Roaster"
SubscriptionPlanVariation, which is a yearly membership with a static price.
- There is no
RELATIVEpricing in this
SubscriptionPlanVariation, so you don't need to include an order template or phases in the request.
card_idrepresents a card on file to charge and the
start_dateis set to a future date.
The response shows the subscription's status as
PENDING. When the start date arrives, the status changes to
ACTIVE. Square charges the card on file based on the subscription plan variation and sends an invoice receipt to the customer's email address. If the subscription plan offers an initial free phase, the customer is billed (invoiced or charged) only after the free phase.
You can modify or clear subscription field values by calling UpdateSubscription. For example, you can update a
card_id on file or clear an upcoming
In the request body, include the
Subscription object with only the fields you want to update. To clear a field, set the field value to
null. The following example updates the customer's
card_id and clears the upcoming
canceled_date field on a subscription:
The following is an example response.
To retrieve a specific subscription, call RetrieveSubscription and provide the
subscription_id in the endpoint URL as shown:
To receive a list of all subscriptions, call the SearchSubscriptions endpoint. Optionally, you can use the
query field to filter the subscriptions returned by
source. The following example filters the list to include subscriptions sold at a particular location:
The following is an example response. Subscriptions returned by this endpoint are grouped by location, within each location by customer, and then sorted in