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 for your benefit programs.
• The site must install Wix Stores and add gym merchandise as products.
• 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.

Step 1 | Create a program definition

First, create a program definition, to which you'll add a pool definition in Step 2. This program definition serves as a template for each new member's program, created in Step 4.

To create a program definition, call Create Program Definition, specifying the following parameters:

• namespace: Your benefit programs' namespace.
• 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.

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.

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
2. 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.
3. Call Create Pool Definition, specifying the following poolDefinition parameters:
   • programDefinitionIds: An array containing the ID of the program definition created in Step 1.
   • 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. 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. 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:

1. For each piece of gym merchandise you want to be redeemable, use Query Products to retrieve its product ID.
2. To create items, call Bulk Create Items, 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.
   • providerAppId: The Wix Stores app ID: 215238eb-22a5-4c36-9e7b-e7c08025e04e
   • namespace: Your benefit programs' namespace.

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 for the member from the program definition created in Step 1.
• 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. Specify the following parameters:
   • poolDefinitionLookupId.programDefinitionId: The ID of the program definition created in Step 1.
   • beneficiary.memberId: The new member's site member ID.
   • namespace: Your benefit programs' namespace.
   • 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.
2. To renew the program monthly, schedule your app or site to call Renew Program, specifying the program's ID, at the end of each month.
3. To end the program after 12 months, schedule your app or site to call End Program, 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 to issue a token:

1. Retrieve the member's pool by calling Query Pools, 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.
2. If the member is a new member, increase their balance by 1 credit. To do so, call Change Balance, 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, 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.
2. If the member is a new member, check which benefits they have enough credits to redeem:
   1. Call Bulk Check Benefit Eligibility, specifying the following parameters:
      • namespace: Your benefit programs' namespace.
      • benefitSelectors: An array of objects representing the items created in Step 3. 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 to retrieve the products.
        • itemReference.providerAppId: The Wix Stores app ID: 215238eb-22a5-4c36-9e7b-e7c08025e04e
   2. In the response, results.result.eligibleOptions.eligibleBenefits is an array of items that can be redeemed.
      • 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. 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, 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.
2. From the pool's benefits, retrieved in Step 6, find the benefit that has the same itemSetId as the selected item. Save this benefit's benefitKey and price.
3. To redeem the item, call Redeem Benefit, specifying the following parameters:
   • poolId: ID of the pool retrieved in Step 6.
   • itemReference.externalId: Item's externalId retrieved in Step 6.
   • 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.

   Note: Redeeming a benefit automatically deducts the benefit's price from the pool's associated balance.

4. Handle item delivery.