Subscription Contracts API: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

Retrieve the subscription terms behind a recurring order

An order created for a subscription holds the items and prices of one billing cycle. The subscription contract holds the terms future cycles are charged with, including changes made after checkout. For example, a fulfillment app may want to show the items and quantities the buyer will receive next.

To retrieve the subscription terms behind a recurring order:

1. Call Get Order to retrieve the order.

2. In the order's lineItems, find the line items that have subscriptionInfo. Save subscriptionInfo.id.

3. Call Get Subscription Contract and specify the saved subscriptionInfo.id as subscriptionContractId.

4. Read the current terms from the subscription contract's lineItems, subscriptionSettings, and recipientInfo.

5. Optionally, to retrieve the other orders created from the same subscription contract, call Search Orders with a filter on lineItems.subscriptionInfo.id. For example:

   Copy

Retrieve the subscriptions created at checkout

A buyer can check out with several subscription items at once. The checkout creates a subscription contract for each group of items that are billed together, so 1 order can hold line items from several subscription contracts. For example, a fulfillment app may want to set up a recurring shipment for each subscription the buyer bought.

To retrieve the subscriptions created at checkout:

1. Call Get Order to retrieve the checkout order.

2. In the order's lineItems, save each distinct subscriptionInfo.id. Line items with the same subscriptionInfo.id belong to the same subscription contract.

3. Call Query Subscription Contracts with a filter on id that holds the saved IDs, and cursorPaging.limit set to 100. For example:

   Copy

4. While pagingMetadata.hasNext is true, call Query Subscription Contracts again with cursorPaging.cursor set to pagingMetadata.cursors.next.

5. For each subscription contract you retrieved, set up the recurring shipment with the billing schedule in subscriptionSettings and the items in lineItems.

List all subscriptions of a buyer

A support agent helping a buyer needs to see every subscription the buyer has and what each one includes. For example, a customer support app may want to show the agent each subscription's items, billing schedule, and price.

To list all subscriptions of a buyer:

1. Get the buyer's contact ID. For example, call Get Order with one of the buyer's orders, and save buyerInfo.contactId.

2. Call Query Subscription Contracts with a filter on buyerInfo.contactId, and cursorPaging.limit set to 100. For example:

   Copy

   The results also include subscriptions that ended, because a subscription contract isn't deleted when its subscription ends.

3. While pagingMetadata.hasNext is true, call Query Subscription Contracts again with cursorPaging.cursor set to pagingMetadata.cursors.next.

4. Show the agent each subscription contract's subscriptionTitle, lineItems, subscriptionSettings, and priceSummary.

5. Optionally, to show the orders of a subscription, call Search Orders with a filter on lineItems.subscriptionInfo.id set to the subscription contract's id.

Sync subscription contracts with an external system

An external system, such as an ERP or a fulfillment service, may keep its own copy of each subscription contract. The copies must stay current as buyers check out and as changes from draft subscription contracts are committed. Start listening to events before you import, so changes made during the import aren't missed.

Part 1: Listen for changes

To listen for changes:

1. Listen to Subscription Contract Created, and save each new subscription contract. A checkout with several groups of subscription items triggers 1 event for each subscription contract.
2. Listen to Subscription Contract Updated. When your system has no copy of the subscription contract, or the subscription contract's revision in the event is higher than your copy's, save the subscription contract from the event.
3. Optionally, to keep a history of changes, listen to Subscription Contract Committed. Save changes, which holds the line items, discounts, and additional fees that were added, changed, or removed, and reason.
4. Listen to Subscription Contract Deleted, and delete your copy. The event is triggered when the buyer's personal data is erased. When a site is permanently deleted, its subscription contracts are deleted without this event.

Part 2: Import the existing subscription contracts

To import the existing subscription contracts:

1. Call Query Subscription Contracts with cursorPaging.limit set to 100. Save each subscription contract in your system, unless an event already saved a copy with the same or a higher revision.
2. While pagingMetadata.hasNext is true, call Query Subscription Contracts again with cursorPaging.cursor set to pagingMetadata.cursors.next, and save the results the same way.