About the Subscription Contracts API

The Subscription Contracts API lets you retrieve the terms of a buyer's subscription: the subscribed items and their prices, the billing frequency and number of billing cycles, and the buyer, billing, and shipping details agreed on at checkout, or as later changed through draft subscription contracts.

With the Subscription Contracts API, you can:

• Retrieve a subscription contract by ID.
• Query a site's subscription contracts. For example, retrieve all of a buyer's subscriptions.
• Listen to events when a subscription contract is created, updated, or deleted, or when changes to it are committed.

Subscription contracts and orders

When a buyer checks out with subscription items, a subscription contract is created for each group of items that are billed together:

• Physical items (itemType.preset is PHYSICAL) from the same catalog (catalogReference.appId) with identical subscriptionInfo.subscriptionSettings share 1 subscription contract. For example, 2 Wix Stores products with the same monthly subscription settings.
• Every other subscription item gets its own subscription contract, even when its subscription settings match another item's. For example, each Wix Pricing Plans plan gets its own subscription contract.

So 1 checkout can create several subscription contracts. Each billing cycle, an order is created from each subscription contract's current content.

A subscription contract doesn't hold the IDs of its orders. Instead, each order's subscription line items point back to the contract:

• lineItems.subscriptionInfo.id: ID of the subscription contract the order was created from.
• lineItems.subscriptionInfo.cycleNumber: Billing cycle the order is for.

To retrieve all the orders created from a subscription contract, call Search Orders with a filter on lineItems.subscriptionInfo.id.

Changes to a subscription contract apply to the orders created after the change. Orders that were already created keep their content.

Before you begin

It's important to note the following points before starting to code:

• You can't create subscription contracts with this API. They're created when a buyer checks out with a subscription item.
• You can't update subscription contracts with this API. To change a subscription contract, use the Draft Subscription Contracts API: create a draft from the contract, edit the draft, and commit it.
• Query Subscription Contracts supports filtering and sorting by id and buyerInfo.contactId only.
• Get Subscription Contract and Query Subscription Contracts return any subscription contract on the site, regardless of who bought it.

Use cases

• Retrieve the subscription terms behind a recurring order
• Retrieve the subscriptions created at checkout
• List all subscriptions of a buyer
• Sync subscription contracts with an external system

Terminology

• Subscription contract: The terms of a buyer's subscription: the items, prices, billing schedule, and buyer, billing, and shipping details. Each billing cycle's order is created from it.
• Billing cycle: One recurring charge period of a subscription. Billing cycles are numbered from 1. For example, with a monthly subscription, each month is a billing cycle. When a subscription starts with a free trial, the order created at checkout is for cycle 0.
• Draft subscription contract: A temporary, editable copy of a subscription contract. Committing it applies its changes to the subscription contract from the next billing cycle onward.