> 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/benefit-programs/sample-flows.md

## Article Content:

# Sample Flows

This article shares a possible use case your app or site could support, as well as a sample flow that could support it. This can be a helpful jumping-off point as you plan your app's implementation.

## Create and manage a rewards program for new gym members
This flow creates a rewards program for new members at a gym. 

This flow implements the following functionality.
- Each time the new member comes to the gym, they receive a token. A member is considered "new" for 1 year.
- Gym merchandise, sold on the site, can be redeemed for 10, 20, or 30 tokens, depending on the item.
- Members can roll over up to 5 tokens from one month to the next.

## Prerequisites
This flow has the following prerequisites.
- Decide on a [namespace](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/namespaces.md) for your benefit programs.
- The site must install [Wix Stores](https://www.wix.com/app-market/web-solution/wix-stores) and add gym merchandise as [products](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/introduction.md).
- All gym members are also site members. When a member visits the gym, your app or site is notified and provided with the site member's ID.

> **Note**: This article only specifies parameters required for this flow. For each API call, refer to the API reference to see the full list of parameters.

## Step 1 | Create a program definition 
First, create a program definition, to which you'll add a pool definition in [Step 2](#step-2--create-a-pool-definition). This program definition serves as a template for each new member's program, created in [Step 4](#step-4--create-a-program-for-new-members).

To create a program definition, call [Create Program Definition](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/program-definitions/create-program-definition.md), specifying the following parameters:
- `namespace`: Your [benefit programs' namespace](#prerequisites).
- `externalProgramId`: This can be whatever you want, but it must be unique in your app or site.

Save the program definition's ID included in the response.

> **Note:** This step could be omitted for this flow, and in [Step 4](#step-4--create-a-program-for-new-members) the program could be created from the pool definition created in [Step 2](#step-2--create-a-pool-definition). However, we are creating a program definition so that more pool definitions could be added to the program definition in future.

## Step 2 | Create a pool definition
Next, create a pool definition, which serves as a template for the pool in each new member's program, which you'll create in [Step 4](#step-4--create-a-program-for-new-members).

You need to specify an array of benefits and credit configuration in substep 3 of this step. In this flow, we have broken it out into different substeps, but you may skip straight to substep 3 and define the benefits array and credit configuration in the API call.

To create a pool definition:
1. Define an array of benefits. 
    We need 3 benefits because we have 3 prices for gym merchandise. For each benefit, specify the following fields:
    - `benefitKey`: We can define each however we want. Let's call them `gym10`, `gym20`, and `gym30`.
    - `price`: `10`, `20`, and `30`.
    - `providerAppId`: The Wix Stores app ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`
1. Define a `creditConfiguration` object. Specify the following fields:
    - `amount`: `0`. Indicates that new members start with 0 tokens.
    - `rolloverConfiguration.enabled`: `true`. Indicates that members can roll over tokens.
    - `rolloverConfiguration.balanceCap`: `5`. Indicates that members can roll over up to 5 tokens.
    - `unitDisplayName`: `Tokens`. Defines the display unit for the credits.
1. Call [Create Pool Definition](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pool-definitions/create-pool-definition.md), specifying the following `poolDefinition` parameters:
    - `programDefinitionIds`: An array containing the ID of the program definition created in [Step 1](#step-1--create-a-program-definition).
    - `details.benefits`: The `benefits` array defined earlier in this step.
    - `details.creditConfiguration`: The `creditConfiguration` object defined earlier in this step.
    - `namespace`: Your [benefit programs' namespace](#prerequisites).
    Save each benefit's `itemSetId` included in the response.

## Step 3 | Create benefit items
Next, create benefit items and assign them to benefits in the pool definition created in the previous step. The gym merchandise already [exists as products](#prerequisites). This step associates each product with a specific benefit in the pool definition.

To create benefit items and add them to the benefits created in [Step 2](#step-2--create-a-pool-definition):
1. For each piece of gym merchandise you want to be redeemable, use [Query Products](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/query-products.md) to retrieve its product ID.
1. To create items, call [Bulk Create Items](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/items/bulk-create-items.md), specifying the following parameters in the `items` array for each piece of gym merchandise:
    - `externalId`: The product ID retrieved from Wix Stores.
    - `itemSetId`: Use the `itemSetId` from the relevant benefit, saved in [Step 2](#step-2--create-a-pool-definition).
    - `providerAppId`: The Wix Stores app ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`
    - `namespace`: Your [benefit programs' namespace](#prerequisites).

## Step 4 | Create a program for new members
Next, write code that runs each time a new member joins the gym. The code should: 
- [Provision a program](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/benefit-programs-lifecycle.md#provisioning-programs) for the member from the program definition created in [Step 1](#step-1--create-a-program-definition).
- Renew the program monthly.
- End the program after 1 year.

When a new member joins the gym:
1. Create a program for the new member by calling [Provision Program](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/programs/provision-program.md). Specify the following parameters:
    - `poolDefinitionLookupId.programDefinitionId`:  The ID of the program definition created in [Step 1](#step-1--create-a-program-definition).
    - `beneficiary.memberId`: The new member's site member ID.
    - `namespace`: Your [benefit programs' namespace](#prerequisites).
    - `externalProgramId`: This can be whatever you want, but it must be unique in your app or site. To ensure uniqueness, use a combination of the `programDefinitionID` and `memberId`. For example, `<programDefinitionID>_<memberId>`.
    Save the program's ID included in the response.
1. To renew the program monthly, schedule your app or site to call [Renew Program](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/programs/renew-program.md), specifying the program's ID, at the end of each month.
1. To end the program after 12 months, schedule your app or site to call [End Program](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/programs/end-program.md), specifying the program's ID, after 12 months.

## Step 5 | Issue a token
Next, write code that runs each time a new member visits the gym. The code should retrieve the member's pool's ID, checking whether there is an active pool when doing so. If an active pool exists, the member is a new member. Then, use the pool ID to update the pool's associated balance.

When a member visits the gym, [use their site member ID](#prerequisites) to issue a token: 
1. Retrieve the member's pool by calling [Query Pools](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/query-pools.md), filtering by `beneficiary.memberId`, `namespace`, and whether `status` is `ACTIVE`. \
Since we've only created programs from 1 program definition, which contains 1 pool definition, in this flow, we'd expect the following:
    - **New members**: 1 pool is included in the response. Save this pool's ID.
    - **Old member**: No pools are returned in the response.
1. If the member is a new member, increase their balance by 1 credit. To do so, call [Change Balance](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/balances/change-balance.md), specifying the following parameters:
    - `poolId`: The ID of the pool retrieved earlier in this step.
    - `idempotencyKey`: Generate a GUID. Use the same string if you repeat the call due to an error.
    - `adjustOptions.value`: `1`. Increases the pool's balance by 1 token.
In this step, you've added code to issue a token to each member every time they visit the gym.

## Step 6 | Show members their redeemable benefits
Next, write code that displays to members all the benefits they can redeem. To check this, you need to retrieve:
- The member's pool's ID, checking whether there is an active pool when doing so. If an active pool exists, the member is a new member.
- The product IDs of the gym merchandise.

When a member logs in to the site:
1. Retrieve the member's pool by calling [Query Pools](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/query-pools.md), filtering by `beneficiary.memberId`, `namespace`, and whether `status` is `ACTIVE`. \
Since we've only created programs from 1 program definition, which contains 1 pool definition, in this flow, we'd expect the following:
    - **New members**: 1 pool is included in the response. Save this pool's ID and `details.benefits`.
    - **Old member**: No pools are returned in the response.
1. If the member is a new member, check which benefits they have enough credits to redeem:
    1. Call [Bulk Check Benefit Eligibility](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/bulk-check-benefit-eligibility.md), specifying the following parameters:
        - `namespace`: Your [benefit programs' namespace](#prerequisites).
        - `benefitSelectors`: An array of objects representing the items created in [Step 3](#step-3--create-benefit-items). For each object, specify the following parameters:
            - `poolId`: ID of the pool retrieved earlier in this step.
            - `itemReference.externalId`: The product ID retrieved from Wix Stores. You can use [Query Products](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/query-products.md) to retrieve the products.
            - `itemReference.providerAppId`: The Wix Stores app ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`
    1. In the response, `results.result.eligibleOptions.eligibleBenefits` is an array of items that can be [redeemed](https://dev.wix.com/docs/api-reference/business-solutions/benefit-programs/introduction.md).
        - If this array is empty, there are no items that can be redeemed.
        - If this array is not empty, using the `externalId` of each redeemable item, retrieve the redeemable gym merchandise products from Wix Stores using [Query Products](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/query-products.md). Display the items in a way that allows the site member to select one.

## Step 7 | Allow a member to redeem an item
Next, handle the flow if a site member selects an item to redeem.

If the site member selects an item to redeem:
1. Retrieve the selected item by calling [Query Items](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/items/query-items.md), filtering by `externalId` and the Wix Stores `providerAppId`, `215238eb-22a5-4c36-9e7b-e7c08025e04e`. There should be 1 item in the response. Save this item's `itemSetId`.
1. From the pool's benefits, retrieved in [Step 6](#step-6--show-members-their-redeemable-benefits), find the benefit that has the same `itemSetId` as the selected item. Save this benefit's `benefitKey` and `price`.
1. To redeem the item, call [Redeem Benefit](https://dev.wix.com/docs/rest/business-solutions/benefit-programs/pools/redeem-benefit.md), specifying the following parameters:
    - `poolId`: ID of the pool retrieved in [Step 6](#step-6--show-members-their-redeemable-benefits).
    - `itemReference.externalId`: Item's `externalId` retrieved in [Step 6](#step-6--show-members-their-redeemable-benefits).
    - `itemReference.providerAppId`: The Wix Stores app ID: `215238eb-22a5-4c36-9e7b-e7c08025e04e`
    - `benefitKey`: Benefit key retrieved earlier in this step.
    - `idempotencyKey`: Generate a GUID. Use the same string if you repeat the call due to an error.
    - `namespace`: Your [benefit programs' namespace](#prerequisites).
    > **Note:** Redeeming a benefit automatically deducts the benefit's price from the pool's associated balance.
1. Handle item delivery.