> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Sample Flows

## Article: Sample Flows

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/sample-flows.md

## Article Content:

# 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) with the subscription contract ID. Check that `draftable` is `true`, and save `currentCycleNumber`.
1. Call [Create Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md) 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.
1. Get the catalog item ID of the product to add. For a Wix Stores product, call [Query Products](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/query-products.md), and use the product ID as `catalogItemId`. To add a specific variant, call [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product.md) and save the variant ID.
1. Call [Add Line Items](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/add-line-items.md) with the product in `catalogLineItems`. The product must come from the same catalog as the subscription's other products. For example:

    ```json
    {
      "catalogLineItems": [
        {
          "catalogReference": {
            "catalogItemId": "<PRODUCT_ID>",
            "appId": "<CATALOG_APP_ID>",
            "options": {
              "variantId": "<VARIANT_ID>"
            }
          },
          "quantity": 1
        }
      ]
    }
    ```

1. Show the merchant the recalculated `priceSummary` from the response, and any `calculationErrors`.
1. Call [Commit Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/commit-draft-subscription-contract.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) with the subscription contract ID. Check that `draftable` is `true`, and save `currentCycleNumber`.
1. Call [Create Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md) 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`.
1. Call [Update Line Items](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/update-line-items.md) 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.
1. Show the merchant the line item's `changeType` and the recalculated `priceSummary`. Check `discounts` and `additionalFees` for entries whose `applied` changed to `false`.
1. Call [Commit Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/commit-draft-subscription-contract.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) with the subscription contract ID. Check that `draftable` is `true`, and save `currentCycleNumber`.
1. Call [Create Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md) with `target.contractTarget.nextCycleNumber` set to `currentCycleNumber` + 1. Find the line item in `draftSubscriptionContract.lineItems`, and save its `lineItem.id`.
1. Call [Update Line Items](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/update-line-items.md) 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.
1. Show the merchant the line item's `changedDetails.priceBeforeChange` and the recalculated `priceSummary`.
1. Call [Commit Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/commit-draft-subscription-contract.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) with the subscription contract ID. Check that `draftable` is `true`, and save `currentCycleNumber`.
1. Call [Create Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md) with `target.contractTarget.nextCycleNumber` set to `currentCycleNumber` + 1. Save the draft subscription contract ID.
1. Call [Add Line Items](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/add-line-items.md) with the extra in `customLineItems`. Specify the item name, price, and quantity. For example:

    ```json
    {
      "customLineItems": [
        {
          "productName": {
            "original": "Gift wrapping"
          },
          "price": {
            "amount": "3.00"
          },
          "quantity": 1
        }
      ]
    }
    ```

1. Show the merchant the recalculated `priceSummary`.
1. Call [Commit Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/commit-draft-subscription-contract.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) with the subscription contract ID. Check that `draftable` is `true`, and save `currentCycleNumber`.
1. Call [Create Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md) with `target.contractTarget.nextCycleNumber` set to `currentCycleNumber` + 1. The site member must be the buyer of the subscription contract.
1. Find the line item in `draftSubscriptionContract.lineItems`. For a Wix Stores product, `lineItem.catalogReference.catalogItemId` is the product ID. Call [Get Product](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/get-product.md) with the product ID, show the member the product's variants, and save the ID of the variant the member chooses.
1. Call [Update Line Items](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/update-line-items.md) 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.
1. Show the member the recalculated `priceSummary`.
1. Call [Commit Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/commit-draft-subscription-contract.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/get-subscription-contract-draftability.md) with the subscription contract ID.
1. If `draftable` is `true`, call [Create Draft Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/create-draft-subscription-contract.md). 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/delete-draft-subscription-contract.md) and create a new one to start over.
1. 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/draft-subscription-contracts/delete-draft-subscription-contract.md) with the draft subscription contract ID. The subscription contract doesn't change, and you can create another draft subscription contract for it later.