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

Add a product to a subscription before the next billing cycle

A merchant wants to add a product to a buyer's subscription, for example a free gift or an extra item, without canceling the subscription. The change applies from the next billing cycle onward.

To add a product to a subscription:

1. Call Get Subscription Contract Draftability with the subscription contract ID. Check that draftable is true, and save currentCycleNumber.

2. Call Create Draft Subscription Contract with the subscription contract ID and target.contractTarget.nextCycleNumber set to currentCycleNumber + 1. Save the draft subscription contract ID from calculatedDraftSubscriptionContract.draftSubscriptionContract.id. Save catalogReference.appId from any line item in draftSubscriptionContract.lineItems. This is the ID of the catalog the subscription's products come from.

3. Get the catalog item ID of the product to add. For a Wix Stores product, call Query Products, and use the product ID as catalogItemId. To add a specific variant, call Get Product and save the variant ID.

4. Call Add Line Items with the product in catalogLineItems. The product must come from the same catalog as the subscription's other products. For example:

   Copy

5. Show the merchant the recalculated priceSummary from the response, and any calculationErrors.

6. Call Commit Draft Subscription Contract with the draft subscription contract ID.

Change the quantity of a subscription item

A buyer asks the merchant to change how many units of an item they get in each billing cycle. To remove the item, the merchant sets its quantity to 0.

To change the quantity of a subscription item:

1. Call Get Subscription Contract Draftability with the subscription contract ID. Check that draftable is true, and save currentCycleNumber.
2. Call Create Draft Subscription Contract with the subscription contract ID and target.contractTarget.nextCycleNumber set to currentCycleNumber + 1. Find the line item to change in draftSubscriptionContract.lineItems, and save its lineItem.id.
3. Call Update Line Items with the line item ID and newQuantity in lineItemChanges. A line item linked to a discount or an additional fee can only be removed or restored to its original quantity.
4. Show the merchant the line item's changeType and the recalculated priceSummary. Check discounts and additionalFees for entries whose applied changed to false.
5. Call Commit Draft Subscription Contract with the draft subscription contract ID. To change the subscription without notifying the buyer, set settings.sendNotificationsToBuyer to false.

Change the price of a subscription item

A merchant gives a buyer a new price for an item, for example a loyalty price, from the next billing cycle onward.

To change the price of a subscription item:

1. Call Get Subscription Contract Draftability with the subscription contract ID. Check that draftable is true, and save currentCycleNumber.
2. Call Create Draft Subscription Contract with target.contractTarget.nextCycleNumber set to currentCycleNumber + 1. Find the line item in draftSubscriptionContract.lineItems, and save its lineItem.id.
3. Call Update Line Items with the line item ID and newPrice in lineItemChanges. The price includes the item's modifiers. A new price sets applied to false for the discounts linked to the line item. Exception: when settings.specificItemsCouponBehavior is ITEM_SUBTOTAL_INCLUDES_DISCOUNT, a GLOBAL discount stays applied and is recalculated. A line item linked to an additional fee can't get a new price.
4. Show the merchant the line item's changedDetails.priceBeforeChange and the recalculated priceSummary.
5. Call Commit Draft Subscription Contract with the draft subscription contract ID.

Add a one-off extra to a subscription

A merchant adds something that isn't in the catalog to a buyer's subscription, for example a surcharge for gift wrapping, from the next billing cycle onward.

To add a one-off extra to a subscription:

1. Call Get Subscription Contract Draftability with the subscription contract ID. Check that draftable is true, and save currentCycleNumber.

2. Call Create Draft Subscription Contract with target.contractTarget.nextCycleNumber set to currentCycleNumber + 1. Save the draft subscription contract ID.

3. Call Add Line Items with the extra in customLineItems. Specify the item name, price, and quantity. For example:

   Copy

4. Show the merchant the recalculated priceSummary.

5. Call Commit Draft Subscription Contract with the draft subscription contract ID.

Let a buyer change the variant of a subscription item

A site member wants to change the variant of an item in their subscription, for example a different size or flavor. Your site lets the member make the change from their account page.

To let a buyer change the variant of a subscription item:

1. As the site member, call Get Subscription Contract Draftability with the subscription contract ID. Check that draftable is true, and save currentCycleNumber.
2. Call Create Draft Subscription Contract with target.contractTarget.nextCycleNumber set to currentCycleNumber + 1. The site member must be the buyer of the subscription contract.
3. Find the line item in draftSubscriptionContract.lineItems. For a Wix Stores product, lineItem.catalogReference.catalogItemId is the product ID. Call Get Product with the product ID, show the member the product's variants, and save the ID of the variant the member chooses.
4. Call Update Line Items with the line item ID and newCatalogReferenceOptions.options set to the new variant ID and the line item's current subscriptionOptionId. The new options replace all of the line item's catalog reference options. Don't specify newPrice, because a site member can't set prices. The price of the new variant comes from the catalog.
5. Show the member the recalculated priceSummary.
6. Call Commit Draft Subscription Contract with the draft subscription contract ID.

Resume or replace an existing draft

A merchant opens a subscription for editing, but a draft subscription contract already exists for it.

To resume or replace an existing draft:

1. Call Get Subscription Contract Draftability with the subscription contract ID.
2. If draftable is true, call Create Draft Subscription Contract. When preexistingDraftSubscriptionContract is true, the response holds your own draft subscription contract with your earlier changes. Continue editing it, or call Delete Draft Subscription Contract and create a new one to start over.
3. If nonDraftableReasons includes DRAFT_ALREADY_EXISTS_FOR_ANOTHER_OWNER, another identity is editing the subscription. Show the merchant who, from createdBy. Only that identity can commit or delete the draft subscription contract. Otherwise, it expires 24 hours after its last change, or when the next billing cycle starts.

Discard a subscription edit

A merchant starts to edit a subscription and then decides not to apply the changes.

To discard a subscription edit:

1. Call Delete Draft Subscription Contract with the draft subscription contract ID. The subscription contract doesn't change, and you can create another draft subscription contract for it later.