> 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-management/marketing/sample-flows.md

## Article Content:

# Referral Program APIs: Sample Flows

This article shows sample use cases and flows you can implement. Use it as a starting point when you plan your implementation.

## Set up a referral program

When a Wix user installs the Referral Program app, a referral program is created with `status: "DRAFT"` by default.

To edit and activate the referral program:

1. Call [Get Referral Program](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referral-program/get-referral-program.md) to retrieve the existing referral program and review its current configuration.

2. Call [Update Referral Program](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referral-program/update-referral-program.md) to configure your program settings such as rewards for referred friends and referring customers, and to set successful referral actions.

   ::::tabs
   :::REST_TAB
   ```json
   {
     "referralProgram": {
       "name": "Holiday Referral Program",
       "referredFriendReward": {
         "type": "COUPON",
         ...
       },
       "referringCustomerReward": {
         "type": "LOYALTY_POINTS", 
         "loyaltyPointsOptions": {
           "amount": 100
         }
       },
       "successfulReferralActions": ["STORE_ORDER_PLACED"],
       "emails": {
         "encourageToReferFriends": ["STORES"],
         "notifyCustomersAboutReward": true
       }
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { programs } from "@wix/referral";

   const updatedProgram = await programs.updateReferralProgram({
     name: "Holiday Referral Program",
     referredFriendReward: {
       type: "COUPON",
       ...
     },
     referringCustomerReward: {
       type: "LOYALTY_POINTS",
       loyaltyPointsOptions: {
         amount: 100
       }
     },
     successfulReferralActions: ["STORE_ORDER_PLACED"],
     emails: {
       encourageToReferFriends: ["STORES"],
       notifyCustomersAboutReward: true
     }
   });
   ```
   :::
   ::::

3. When you're ready to make the referral program live, call [Update Referral Program](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referral-program/update-referral-program.md) again and set `status: "ACTIVE"`.

   ::::tabs
   :::REST_TAB
   ```json
   {
     "referralProgram": {
       "status": "ACTIVE"
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { programs } from "@wix/referral";

   const activatedProgram = await programs.updateReferralProgram({
     status: "ACTIVE"
   });
   ```
   :::
   ::::

4. When you have a customer who wants to participate in referrals, call [Generate Referring Customer For Contact](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referring-customers/generate-referring-customer-for-contact.md) to create a referring customer record and generate the referral code.

   ::::tabs
   :::REST_TAB
   ```json
   {
     "contactId": "contact-id-123"
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { customers } from "@wix/referral";

   const referringCustomer = await customers.generateReferringCustomerForContact({
     contactId: "contact-id-123"
   });
   const referralCode = referringCustomer.referralCode;
   ```
   :::
   ::::

5. Share the generated referral code with the referring customer so they can distribute it to friends.


## Process friend signups

When someone uses a referral code (for example, during a purchase, booking, event registration, or other qualifying action), validate the referral code and create the connection between the referring customer and the referred friend to ensure you can track referrals and distribute rewards correctly.

To process friend signups:

1. When a friend provides a referral code, call [Query Referring Customers](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referring-customers/query-referring-customers.md) and filter by the referral code, to validate that it's a real referral code and which customer is associated with it. The response includes the `referringCustomerId` that you'll need in step 3:

   ::::tabs
   :::REST_TAB
   ```json
   {
     "query": {
       "filter": {
         "referralCode": {
           "eq": "GxpxwAoMqxH8"
         }
       }
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { customers } from "@wix/referral";

   const { items } = await customers.queryReferringCustomers({
     filter: { 
       referralCode: "GxpxwAoMqxH8" 
     }
   });
   const referringCustomerId = items[0]._id;
   ```
   :::
   ::::

2. If the code is valid, get the contact ID of the friend who used the referral code (this could be from a contact you create, an existing contact, or a contact associated with a purchase, booking, or other action). Then call [Query Referred Friend](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referred-friends/query-referred-friend.md) to check if this contact is already a referred friend:

   ::::tabs
   :::REST_TAB
   ```json
   {
     "query": {
       "filter": {
         "contactId": {
           "eq": "friend-contact-id-456"
         }
       }
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { friends } from "@wix/referral";

   const { items } = await friends.queryReferredFriend({
     filter: { 
       contactId: "friend-contact-id-456" 
     }
   });
   ```
   :::
   ::::

3. If the contact is already a referred friend, stop here. If the contact isn't already a referred friend, call [Create Referred Friend](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referred-friends/create-referred-friend.md) to link the contact as a referred friend to the referring customer. Use the `referringCustomerId` from step 1.

   ::::tabs
   :::REST_TAB
   ```json
   {
     "referredFriend": {
       "contactId": "friend-contact-id-456",
       "referringCustomerId": "referring-customer-id-789"
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { friends } from "@wix/referral";

   const referredFriend = await friends.createReferredFriend({
     contactId: "friend-contact-id-456",
     referringCustomerId: "referring-customer-id-789"
   });
   ```
   :::
   ::::

## Track referral program performance

To monitor your referral program and understand which customers are your best referrers and how well your program is performing, run these queries regularly. This information can guide decisions about program adjustments or customer outreach.

1. Call [Query Referring Customers](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referring-customers/query-referring-customers.md) to get all customers participating in referrals:

   ::::tabs
   :::REST_TAB
   ```json
   {
     "query": {}
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { customers } from "@wix/referral";

   const { items } = await customers.queryReferringCustomers({});
   ```
   :::
   ::::

2. Call [Query Referred Friend](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referred-friends/query-referred-friend.md) to get all referred friends, sorted by `referringCustomerId`. Then count how many referrals each customer has made:

   ::::tabs
   :::REST_TAB
   ```json
   {
     "query": {
       "sort": [
         {
           "fieldName": "referringCustomerId",
           "order": "ASC"
         }
       ]
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { friends } from "@wix/referral";

   const { items } = await friends.queryReferredFriend({
     sort: [{ 
       fieldName: "referringCustomerId", 
       order: "ASC" 
     }]
   });
   
   // Count referrals per customer
   // Result: { "customer-id-1": 5, "customer-id-2": 3, ... }
   const referralsByCustomer = items.reduce((acc, friend) => {
     const customerId = friend.referringCustomerId;
     acc[customerId] = (acc[customerId] || 0) + 1;
     return acc;
   }, {});
   ```
   :::
   ::::

3. Call [Query Referral Rewards](https://dev.wix.com/docs/api-reference/business-management/marketing/referral-program/referral-rewards/query-referral-rewards.md) to analyze reward distribution over a specific time period:

   ::::tabs
   :::REST_TAB
   ```json
   {
     "query": {
       "filter": {
         "createdDate": {
           "gte": "2024-01-01T00:00:00.000Z"
         }
       }
     }
   }
   ```
   :::
   :::SDK_TAB
   ```js
   import { rewards } from "@wix/referral";

   const { items } = await rewards.queryReferralRewards()
     .gte("createdDate", "2024-01-01T00:00:00.000Z")
     .find();
   ```
   :::
   ::::

4. Calculate key performance metrics such as total referrals, conversion rates, and average rewards per customer.