> 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/subscription-contracts/sample-flows.md

## Article Content:

# 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md) to retrieve the order.
1. In the order's `lineItems`, find the line items that have `subscriptionInfo`. Save `subscriptionInfo.id`.
1. Call [Get Subscription Contract](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/get-subscription-contract.md) and specify the saved `subscriptionInfo.id` as `subscriptionContractId`.
1. Read the current terms from the subscription contract's `lineItems`, `subscriptionSettings`, and `recipientInfo`.
1. Optionally, to retrieve the other orders created from the same subscription contract, call [Search Orders](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/search-orders.md) with a filter on `lineItems.subscriptionInfo.id`. For example:

    ```json
    {
      "search": {
        "filter": {
          "lineItems.subscriptionInfo.id": "01d10356-9188-4ab2-90c1-acfcfeb488c1"
        }
      }
    }
    ```

## 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md) to retrieve the checkout order.
1. In the order's `lineItems`, save each distinct `subscriptionInfo.id`. Line items with the same `subscriptionInfo.id` belong to the same subscription contract.
1. Call [Query Subscription Contracts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/query-subscription-contracts.md) with a filter on `id` that holds the saved IDs, and `cursorPaging.limit` set to `100`. For example:

    ```json
    {
      "query": {
        "filter": {
          "id": {
            "$in": ["<SUBSCRIPTION_CONTRACT_ID_1>", "<SUBSCRIPTION_CONTRACT_ID_2>"]
          }
        },
        "cursorPaging": {
          "limit": 100
        }
      }
    }
    ```

1. While `pagingMetadata.hasNext` is `true`, call Query Subscription Contracts again with `cursorPaging.cursor` set to `pagingMetadata.cursors.next`.
1. 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/get-order.md) with one of the buyer's orders, and save `buyerInfo.contactId`.
1. Call [Query Subscription Contracts](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/query-subscription-contracts.md) with a filter on `buyerInfo.contactId`, and `cursorPaging.limit` set to `100`. For example:

    ```json
    {
      "query": {
        "filter": {
          "buyerInfo.contactId": "<CONTACT_ID>"
        },
        "cursorPaging": {
          "limit": 100
        }
      }
    }
    ```

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

1. While `pagingMetadata.hasNext` is `true`, call Query Subscription Contracts again with `cursorPaging.cursor` set to `pagingMetadata.cursors.next`.
1. Show the agent each subscription contract's `subscriptionTitle`, `lineItems`, `subscriptionSettings`, and `priceSummary`.
1. Optionally, to show the orders of a subscription, call [Search Orders](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/search-orders.md) 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/subscription-contract-created.md), and save each new subscription contract. A checkout with several groups of subscription items triggers 1 event for each subscription contract.
1. Listen to [Subscription Contract Updated](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/subscription-contract-updated.md). 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.
1. Optionally, to keep a history of changes, listen to [Subscription Contract Committed](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/subscription-contract-committed.md). Save `changes`, which holds the line items, discounts, and additional fees that were added, changed, or removed, and `reason`.
1. Listen to [Subscription Contract Deleted](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/subscription-contract-deleted.md), 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/subscriptions/subscription-contracts/query-subscription-contracts.md) 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`.
1. 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.