Subscription Plans and 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.

Link to section

Subscription plans

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.

Upsert catalog object

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
		}
	}
}

Link to section

Plan variations

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

Link to section

Phases

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.

Link to section

Pricing and discounts

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.

Note

Be aware that after creating a plan variation, you cannot add, remove, or reorder phases. To make any of these changes, you must create a new SubscriptionPlanVariation. You also have the option to disable a subscription plan or variation, in which case you can no longer create new subscriptions for that variation.

Link to section

Create a subscription plan variation

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.

Upsert catalog object

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"
		}
	}
}

Link to section

Retrieve subscription plans and variations

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.

List catalog

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.

Retrieve catalog object

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
		}
	}
}

Link to section

Update subscription plans and variations

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

Note

When making changes to a subscription plan, you must also include the full list of subscription_plan_variations associated with the plan. To facilitate this, retrieve the plan first and make the desired changes locally before your call UpsertCatalogObject.

The following example updates the name of a subscription plan:

Upsert catalog object

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:

Upsert catalog object

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

Important

Making changes to a subscription plan or variation never impacts existing subscriptions. These continue to be active and billed at the rate defined in the original plan variation. However, changes you make to plans or variations might prevent new subscriptions from being created or limit which items are available for new subscriptions.

Link to section

Disable subscription plans and variations

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.

Link to section

Next steps

Manage Subscriptions Using the Subscriptions API

Docs

Subscription Plans and Variations