Subscription Plans and Variations

Applies to: Subscriptions API | Catalog API

Learn how to set up Square subscription plans and plan variations.

Subscription plans and plan variations are created and managed using the Catalog API. After creating a plan and at least one plan variation, you add subscriptions using the Subscriptions API.

A subscription plan represents what you want to sell in a subscription model. This can be a service, a single item, or all items in a particular category from a seller's inventory. For example, a coffee shop might offer a coffee subscription, where each month subscribers receive a specific bag of beans.

To create a new subscription plan, call UpsertCatalogObject using the SUBSCRIPTION_PLAN object type. You can include specific item or category IDs for the parts of your catalog you want to make subscribable. Alternatively, set all_items to true to allow all items in your catalog to be subscribable as part of this plan. The following example creates a new "Coffee Subscription" subscription plan, where all items in the seller's coffee category are subscribable.

The following is an example response, showing the new subscription plan:

{
	"catalog_object": {
		"type": "SUBSCRIPTION_PLAN",
		"id": "VVH3YXQSQATSL3XR4LIKD3QM",
		"updated_at": "2022-11-09T20:28:12.208Z",
		"created_at": "2022-11-09T20:28:12.208Z",
		"version": 1668025692208,
		"present_at_all_locations": true,
		"subscription_plan_data": {
			"name": "Coffee Subscription",
			"eligible_category_ids": ["2CJLFP5C6G74W3U3HD5YAE5W"],
			"all_items": false
		}
	}
}

Now that you have a subscription plan, you create variations on that plan. A SubscriptionPlanVariation contains data about how the subscribable items are sold (such as the cadence, or frequency, of the orders and pricing information).

Each SubscriptionPlanVariation must contain at least one Phase. This allows you to set distinct periods for the subscription, such as a free or reduced price "trial phase" followed by a recurring charge. Each phase sets how often the subscription is billed to the customer and a number of periods that the phase lasts, using the following fields:

• Ordinal - The position of this phase in the sequence of phases, beginning with 0.
• Cadence - Identifies the billing interval, such as WEEKLY or MONTHLY.
• Periods - The number of cadences that the phase lasts. The period is required along with an ordinal in all phases except the last phase. If no periods are provided, the phase never ends and the subscription plan has no end date.

Each Phase of the SubscriptionPlanVariation contains data about the pricing of the item or service being sold:

• The type of pricing can be RELATIVE or STATIC. If it's STATIC, a price amount must be set, which overrides the price of any items subscribable through the subscription plan. If it's RELATIVE, the price of the subscribable items is included in an order template on the subscription and the combined item prices are used for the price of the PlanVariation.
• Optionally, if you're using RELATIVE pricing, you can include the IDs of CatalogDiscount objects in the discount_ids field to apply that discount during that phase of the subscription. Discounts can be a fixed value, a percentage, or a dynamic value entered at the time of sale.
• As a best practice, use RELATIVE pricing for itemized subscriptions (recurring orders for an item or items) and STATIC pricing for other subscriptions, such as a flat weekly rate for dog walking or a newsletter.

A SubscriptionPlanVariation is a type of CatalogObject and is created with another call to UpsertCatalogObject.

Suppose a coffee shop wants to offer a monthly variation on their coffee subscription, where the first month's bag of beans costs $10 and each subsequent month the recipient receives a 15% discount on the bag of beans. The following example creates this "Coffee of the Month Club" SubscriptionPlanVariation:

• The first phase lasts 1 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.
• The ID of the subscription plan must be included in this call to associate the variation with the plan.

The following is an example response:

{
	"catalog_object": {
		"type": "SUBSCRIPTION_PLAN_VARIATION",
		"id": "CUPS23SKJ7J4FD4F3IMVAEOH",
		"updated_at": "2022-11-09T20:52:58.857Z",
		"created_at": "2022-11-09T20:52:58.857Z",
		"version": 1668027178857,
		"present_at_all_locations": true,
		"subscription_plan_variation_data": {
			"name": "Coffee of the Month Club",
			"phases": [{
					"uid": "CR7TS35JYEVXC5BSDV5N7Z4Y",
					"cadence": "MONTHLY",
					"ordinal": 0,
					"periods": 1,
					"pricing": {
						"type": "STATIC",
						"price": {
							"amount": 1000,
							"currency": "USD"
						}
					}
				},
				{
					"uid": "AW9ES43NVGRFC8AQRK8J5X1S",
					"cadence": "MONTHLY",
					"ordinal": 1,
					"pricing": {
						"type": "RELATIVE",
						"discount_ids": ["5PFBH6YH5SB2F63FOIHJ7HWR"]
					}
				}
			],
			"subscription_plan_id": "VVH3YXQSQATSL3XR4LIKD3QM"
		}
	}
}

You can list all the subscription plans and plan variations for a seller account by calling ListCatalog. In the request, set the type field to a comma-separated list of the CatalogObjectTypes that you want to retrieve. If you don't set a type, the endpoint returns all objects in your catalog. The following request returns every subscription plan for the seller account. The body of each subscription plan includes all plan variations associated with the plan, so this request returns all plans and all plan variations for the seller account.

If you know the ID of the plan or variation you want to access, call RetrieveCatalogObject with a single object_id or BatchRetrieveCatalogObjects with a list of object IDs. Learn more about how to retrieve catalog objects.

The following is an example response that shows an object of the SUBSCRIPTION_PLAN type. Note that each plan variation associated with this plan is listed in the subscription_plan_variations field.

{
"catalog_object": {
"type": "SUBSCRIPTION_PLAN",
	"id": "VVH3YXQSQATSL3XR4LIKD3QM",
	"updated_at": "2022-11-09T20:28:12.208Z",
	"created_at": "2022-11-09T20:28:12.208Z",
	"version": 1668025692208,
	"present_at_all_locations": true,
	"subscription_plan_data": {
		"name": "Coffee Subscription",
"subscription_plan_variations": [{
			"type": "SUBSCRIPTION_PLAN_VARIATION",
			"id": "CUPS23SKJ7J4FD4F3IMVAEOH",
			"updated_at": "2022-11-09T20:52:58.857Z",
			"created_at": "2022-11-09T20:52:58.857Z",		
      "version": 1668027178857,
			"present_at_all_locations": true,
			"subscription_plan_variation_data": {
				"name": "Coffee of the Month Club",
				"phases": [{
					"uid": "CR7TS35JYEVXC5BSDV5N7Z4Y",
					"cadence": "MONTHLY",
					"ordinal": 0, 
"periods": 1,
					"pricing": {
						"type": "STATIC",
						"price": {
							"amount": 1000,
							"currency": "USD"
						}
					}
				},
					{
					"uid": "AW9ES43NVGRFC8AQRK8J5X1S",
					"cadence": "MONTHLY",
					"ordinal": 1,
					"pricing": {
						"type": "RELATIVE",
						"discount_ids": ["5PFBH6YH5SB2F63FOIHJ7HWR"]
						}
				}],
				"subscription_plan_id": "VVH3YXQSQATSL3XR4LIKD3QM"
				}
			}],
			"eligible_category_ids": ["2CJLFP5C6G74W3U3HD5YAE5W"],
			"all_items": false
		}
	}
}

After creation, you can change certain fields on subscription plans and subscription plan variations by calling UpsertCatalogObject. In the request, include the field you want to update as well as the current version of the object to enable optimistic concurrency control.

The following fields in a SUBSCRIPTION_PLAN are editable:

• name
• eligible_item_ids
• eligible_category_ids
• all_items
• present_at_all_locations

The following example updates the name of a subscription plan:

The following fields of a SUBSCRIPTION_PLAN_VARIATION are editable:

• name
• discount_ids
• present_at_all_locations

When making changes to a plan variation, the entire object, including the complete list of phases, must be included in the request. The following example changes the discount applied in the second phase:

If you only need to change the taxes that apply to an item, use the UpdateItemTaxes endpoint.

Subscription plans and plan variations cannot be deleted. However, they can be disabled so that new subscriptions cannot be created. To disable a plan or variation, call UpsertCatalogObject. In the request, include the plan or variation to disable and set present_at_all_locations to false.

By default, all active subscriptions have present_at_all_locations set to true. It's not possible to disable subscription plans or variations on a per-location basis.

When a plan is disabled, existing subscriptions continue to work but you cannot add new subscriptions.

• Manage Subscriptions Using the Subscriptions API