Manage Subscriptions Using the Subscriptions API

After setting up subscription plans and variations on those plans (see Subscription Plans and Variations), you can use the Subscriptions API to create and manage subscriptions.

Link to section

Subscription object

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 status of PENDING and become ACTIVE on 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 SubscriptionPlanVariation to which this customer is subscribing.
canceled_date - The SubscriptionPlanVariation dictates 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 PlanVariation includes any phases with the RELATIVE pricing type, you must also include the same number of phases in the Subscription object. These phases must include ordinals that correspond to the same phases in the SubscriptionPlanVariation and an order_template_id for 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).

Link to section

Phases and order templates

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" SubscriptionPlanVariation.

The first phase lasts a single month and has a static price of $10.
The second phase is priced RELATIVE to 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 phase. The line_items should include the catalog_object_id of the items being purchased, including any modifiers. If any taxes, discounts, or 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 DRAFT.

Create order

The response includes the entire Order object. Take note of the id. It's used in the following step when creating the Subscription.

{
	"order": {
		"id": "x7ClfqqNapjeDMvrQOZhbgVFVKFZY",
		"location_id": "LE40N37TVF5FT",
		"line_items": [{
			"uid": "LOyOBhiehLVVUYgFwTbbzB",
			"catalog_object_id": "KAQJXCONWUSBWPHR62W3DZTO",
			"catalog_version": 1670956504560,
			"quantity": "1",
			"name": "Ethiopian coffee",
			"variation_name": "36oz bag",
			"base_price_money": {
				"amount": 4800,
				"currency": "USD"
			},
			"gross_sales_money": {
				"amount": 4800,
				"currency": "USD"
			},
			"total_tax_money": {
				"amount": 0,
				"currency": "USD"
			},
			"total_discount_money": {
				"amount": 480,
				"currency": "USD"
			},
			"total_money": {
				"amount": 4320,
				"currency": "USD"
			},
			"variation_total_price_money": {
				"amount": 4800,
				"currency": "USD"
			},
			"applied_discounts": [{
				"uid": "wXWXXxw5x7lkaAWH5PLh9",
				"discount_uid": "yQOVUALvqoUnGjL5WufJ8B",
				"applied_money": {
					"amount": 480,
					"currency": "USD"
				}
			}],
			"item_type": "ITEM"
		}],
		"discounts": [{
			"uid": "yQOVUALvqoUnGjL5WufJ8B",
			"catalog_object_id": "5PFBH6YH5SB2F63FOIHJ7HWR",
			"catalog_version": 1670956504560,
			"name": "ten percent off",
			"percentage": "10.0",
			"applied_money": {
				"amount": 480,
				"currency": "USD"
			},
			"type": "FIXED_PERCENTAGE",
			"scope": "ORDER",
			"apply_per_quantity": false
		}],
		"created_at": "2022-12-15T16:13:46.072Z",
		"updated_at": "2022-12-15T16:15:08.827Z",
		"state": "DRAFT",
		"version": 2,
		"total_tax_money": {
			"amount": 0,
			"currency": "USD"
		},
		"total_discount_money": {
			"amount": 480,
			"currency": "USD"
		},
		"total_tip_money": {
			"amount": 0,
			"currency": "USD"
		},
		"total_money": {
			"amount": 4320,
			"currency": "USD"
		},
		"total_service_charge_money": {
			"amount": 0,
			"currency": "USD"
		},
		"net_amounts": {
			"total_money": {
				"amount": 4320,
				"currency": "USD"
			},
			"tax_money": {
				"amount": 0,
				"currency": "USD"
			},
			"discount_money": {
				"amount": 480,
				"currency": "USD"
			},
			"tip_money": {
				"amount": 0,
				"currency": "USD"
			},
			"service_charge_money": {
				"amount": 0,
				"currency": "USD"
			}
		},
		"source": {
			"name": "Sandbox for sq0ids-AJhvDCw3KCZ4pTqxHrr5uQ"
		},
		"net_amount_due_money": {
			"amount": 4320,
			"currency": "USD"
		}
	}
}

Note

If your order template includes service_charges, and the seller is outside the United States or Canada, these are converted into separate line_items when the order template is created.

To learn more about working with orders, see Orders API Overview.

Link to section

Create a subscription

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.

Important

The customer's profile must include a valid email address. Square emails the subscription invoices and receipts to this email address.

Example 1: Coffee of the Month Club

The following 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.

Create subscription

The following response provides the Subscription object:

{
	"subscription": {
		"id": "7217d8ca-1fee-4446-a9e5-8540b5d8c9bb",
		"location_id": "LE40N37TVF5FT",
		"customer_id": "Y3MBJEF62GVTXAP56H7SD2AFJW",
		"start_date": "2023-02-15",
		"status": "ACTIVE",
		"version": 1,
		"created_at": "2023-02-15T16:15:08Z",
		"timezone": "UTC",
		"source": {
			"name": "My Application"
		},
		"phases": [{
			"uid": "2747cd38-e7a5-4879-9b59-88ef272ffacb",
			"ordinal": 0,
			"order_template_id": "x7ClfqqNapjeDMvrQOZhbgVFVKFZY",
			"plan_phase_uid": "CR7TS35JYEVXC5BSDV5N7Z4Y"
		},{
			"uid": "750a5fa8-658c-482c-bfef-437d064afcd3",
			"ordinal": 1,
			"order_template_id": "EH54BLi8oWWbNIxd9nxgDh3UO1RZY",
			"plan_phase_uid": "AW9ES43NVGRFC8AQRK8J5X1S"
		}],
		"plan_variation_id": "CUPS23SKJ7J4FD4F3IMVAEOH"
	}
}

Note the following:

The request doesn't specify a card_id for 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 source name is the name of the application that created the subscription.

Example 2: Static price subscription with a delayed start

The following CreateSubscription request enrolls a customer in a "Friends of the Roaster" SubscriptionPlanVariation, which is a yearly membership with a static price.

There is no RELATIVE pricing in this SubscriptionPlanVariation, so you don't need to include an order template or phases in the request.
The card_id represents a card on file to charge and the start_date is set to a future date.

Create subscription

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.

{
	"subscription": {
		"id": "28d66d75-a6f8-4594-bd5e-3a8bacf3818e",
		"location_id": "LPJKHYR7WFDKN",
		"customer_id": "FN3M4KE6EHP5W74M9FSDZ8VPMC",
		"start_date": "2027-01-01",
		"status": "PENDING",
		"version": 1,
		"created_at": "2023-03-06T19:44:05Z",
		"timezone": "UTC",
		"source": {
			"name": "My Application"
		},
		"plan_variation_id": "XOUNEKCE6NSXQW5NTSQ73MMX",
		"card_id": "{CARD ID}"
	}
}

Link to section

Update subscriptions

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

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:

Update subscription

Note

The canceled_date of a subscription can only be removed to undo a future scheduled cancellation. Clearing the canceled_date field removes the pending cancellation from the subscription.

The following is an example response.

{
  "subscription": {
    "id": "7217d8ca-1fee-4446-a9e5-8540b5d8c9bb",
    "location_id": "LPJKHYR7WFDKN",
    "plan_variation_id": "XOUNEKCE6NSXQW5NTSQ73MMX",
    "customer_id": "AM69AB81FT4479YH9HGWS1HZY8",
    "start_date": "2023-01-30",
    "charged_through_date": "2023-03-13",
    "card_id": "{NEW CARD ID}",
    "status": "ACTIVE",
    "invoice_ids": [
      "inv:0-ChAPSfVYvNewckgf3x4iigN_ENMM",
      "inv:0-ChBQaCCLfjcm9WEUBGxvuydJENMM",
    ],
    "version": 3,
    "created_at": "2023-01-30T19:27:32Z",
    "timezone": "UTC",
    "source": {
      "name": "My Application"
    }
  }
}

Link to section

Retrieve subscriptions

To retrieve a specific subscription, call RetrieveSubscription and provide the subscription_id in the endpoint URL as shown:

Retrieve subscription

To receive a list of all subscriptions, call the SearchSubscriptions endpoint. Optionally, you can use the query field to filter the subscriptions returned by customer_id, location_id, or source. The following example filters the list to include subscriptions sold at a particular location:

Search subscriptions

The following is an example response. Subscriptions returned by this endpoint are grouped by location, within each location by customer, and then sorted in created_at order.

{
"subscriptions": [{
		"id": "28d66d75-a6f8-4594-bd5e-3a8bacf3818e",
		"location_id": "LPJKHYR7WFDKN",
		"customer_id": "FN3M4KE6EHP5W74M9FSDZ8VPMC",
		"start_date": "2023-05-01",
		"status": "PENDING",
		"version": 1,
		"created_at": "2023-03-06T19:44:05Z",
		"timezone": "UTC",
		"source": {
			"name": "My Application"
		},
		"plan_variation_id": "XOUNEKCE6NSXQW5NTSQ73MMX"
	}, 
{
		"id": "596be271-9f29-4b20-82a2-026b2ba3d7ef",
		"location_id": "LPJKHYR7WFDKN",
		"customer_id": "AM69AB81FT4479YH9HGWS1HZY8",
		"start_date": "2023-01-30",
		"charged_through_date": "2023-03-13",
		"status": "ACTIVE",
		"tax_percentage": "3.2",
		"invoice_ids": ["inv:0-ChAPSfVYvNewckgf3x4iigN_ENMM", "inv:0-ChBQaCCLfjcm9WEUBGxvuydJENMM", 
"inv:0-ChDHLgOxCkOQ_y5Vecikg4nuENMM" ],
		"version": 2,
		"created_at": "2023-01-30T19:27:32Z",
		"timezone": "UTC",
		"source": {
			"name": "My Application"
		},
		"plan_variation_id": "XOUNEKCE6NSXQW5NTSQ73MMX"
	}]
}

Docs

Manage Subscriptions Using the Subscriptions API

Subscription object

Phases and order templates

Note

Create a subscription

Important

Update subscriptions

Note

Retrieve subscriptions

On this page