# Reward system ## How it works The reward system encourages users to make purchases in the store using real currency. For each purchase, they earn value points and progress through a reward chain. If users are part of clans, their purchases contribute value points to the entire clan. ![reward example](https://cdn.xsolla.net/developers/current/images/liveops/rewards/reward-example.svg) ### Reward chains You can create individual and clan reward chains and grant users rewards for purchased items. The project can include multiple reward chains of any type. Each chain can have a maximum of 31 steps. For each step, you define the number of value points required to receive a reward. You can also create a personalized reward chain. Personalization allows you to display the chain only to a specific group of authorized users based on their attributes. A personalized reward chain can be designed for either an individual user or a clan. ### Value points User progress in a reward chain is determined by value points. There are two types of value points: individual and clan — corresponding to the reward chain types. > [!NOTE] > It is recommended to use different value points for different reward chains. If the same value points are used in multiple reward chains: - The points balance is shared across all chains, including newly created ones. - In a newly created chain, users retain their previously accumulated points. - Resetting the chain clears the points balance in all chains that share existing value points. - Value points reset is not immediate after a chain period ends. The reset runs 4 times per hour, at :00, :15, :30, and :45. For example, if a chain ends at 12:03, the reset occurs at 12:15.Leave at least 15 minutes between chains that share the same value points — otherwise the balance won’t have time to reset, and users will start the new chain with their previous balance. To reset the progress immediately, use the [Reset reward chain](/api/liveops/reward-chain-value-points-admin/admin-reset-reward-chain) API call. The clan balance is calculated as the sum of its members' balances. Therefore, after a reset, the clan balance is also cleared. ### Rewards At each step in the reward chain, a user can receive 1 to 10 rewards. A clan can also receive 1 to 10 rewards per member at each step. You can reward users with the following item types: - virtual items - virtual currency - virtual currency packages - bundles > [!NOTE] > You can give users value points when they receive [free items](/solutions/web-shop/promotions/free-items/). Accumulated value points motivate users to purchase items with real currency to progress through the reward chain. ## Set up reward system **Audience: all other audiences** You can configure the reward system [via Publisher Account](/liveops/promotion-tools/reward-system/#general_set_up_via_publisher) or [via API](/liveops/promotion-tools/reward-system/#general_set_up_via_api): 1. Create value points. Make sure your store contains [items](/items-catalog/items-type/virtual-items/) that users can purchase to earn value points. 2. Create a reward chain. > [!NOTE] > Before launching a new chain that uses existing value points, reset the value points balance. Otherwise, users will start with their accumulated balance. You can do this in two ways: > - Using the [Reset reward chain](/api/liveops/reward-chain-value-points-admin/admin-reset-reward-chain/) API call. > - In Publisher Account, by checking **Refresh user progress after the chain ends** in the chain [validity period settings](/solutions/web-shop/promotions/reward-system/#general_set_up_via_publisher) — the reset will happen automatically when the chain ends. ### Set up via Publisher Account **End of audience: all other audiences** **Audience: Free-to-play PC games, Premium PC games, Web games** You can configure the reward system in your [account](#general_set_up_in_account) or [via API](#general_set_up_via_api): 1. Create value points. Make sure your store contains [items](/items-catalog/items-type/virtual-items/) that users can purchase to earn value points. 2. Create a reward chain. > [!NOTE] > Before launching a new chain that uses existing value points, reset the value points balance. Otherwise, users will start with their accumulated balance. You can do this in two ways: > - Using the [Reset reward chain](/api/liveops/reward-chain-value-points-admin/admin-reset-reward-chain/) API call. > - In your account, by checking **Refresh user progress after the chain ends** in the chain [validity period settings](/solutions/web-shop/promotions/reward-system/#general_set_up_via_publisher) — the reset will happen automatically when the chain ends. ### Set up in account **End of audience: Free-to-play PC games, Premium PC games, Web games** **Audience: all other audiences** > [!NOTE] > You also can set up the promotion using a [canvas](/liveops/xlms/liveops-management/create-reward-chain/). **End of audience: all other audiences** **Audience: Web games** **End of audience: Web games** To create value points: **Audience: all other audiences** 1. Open your project in Publisher Account and go to the [LiveOps > Rewards](https://publisher.xsolla.com/0/projects/0/storefront/rewards/) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/rewards) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/rewards) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/web-games/account/0/projects/0/storefront/rewards) section. **End of audience: Web games** 2. Click **Create value points**. ![create vp](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/create-vp.svg) 3. Specify the following parameters: - Add an image (optional). - Enter a name. - Enter a unique SKU. - If you create clan value points, turn on the **Use as clan value points** toggle. This setting can’t be changed after the value points are created. - Assign value points: select the items and specify how many value points users receive for purchasing each item. If your store doesn’t yet contain any items yet, you can save the current settings and return to this step later. > [!NOTE] > The item must be [available or partially available for purchase](/items-catalog/catalog-management/manual-item/#create_catalog_create_vc_package). ![new vp](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/new-vp.png) 4. Click **Add line** to insert the desired number of items. 5. Click **Create value points**. To change the settings for a specific value point, click **Edit** in the corresponding row. ![edit vp](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/edit-vp.svg) To create the reward chain: **Audience: all other audiences** 1. Open your project in Publisher Account and go to the [LiveOps > Rewards](https://publisher.xsolla.com/0/projects/0/storefront/rewards/) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/rewards) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/rewards) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/web-games/account/0/projects/0/storefront/rewards) section. **End of audience: Web games** 2. Click **Create reward**. ![create reward](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/create-reward.svg) 3. Choose a chain type — **Individual reward chain** or **Clan reward chain**. 4. Specify the following parameters. If you choose an individual reward chain: - Specify the reward chain name. - Provide a description. - In the drop-down list, select value points. ![create individual chain](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/create-individual-chain.png) a. In the **Clan type** drop-down list, choose a type of a clan. b. Set the parameters of the clan reward chain: 1. Specify the chain name. 2. Provide a description. 3. Specify a title for the reward chain popup header. 4. Specify the tooltip text (what users need to do to earn rewards for their clan). 5. Add an image (optional). 6. In the drop-down list, select value points. ![create clan chain](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/create-clan-chain.png) 5. Click **Next**. 6. Click **Add new step**. 7. Specify the following parameters and click **Save**: - Step name. - Required amount of value points to clame the reward. - Required amount of virtual items for the step. 8. Click **Save**. ![new step](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/new-step.png) 9. Add the required number of steps and click **Next**. 10. If you want to personalize the reward chain: a. Turn on the **Personalized reward chain** toggle. b. Select one of the chain display options: - **Show reward chain to specific users**. Set the [personalization conditions](/authenticate-users/login/features/user-attributes/). In this case, the chain is displayed only to authorized users who meet the specified conditions. - **Show reward chain to users who don’t meet conditions**. For such a chain, you don’t need to specify the [personalization conditions](/authenticate-users/login/features/user-attributes/) — it is applied by default. It means it is displayed to unauthorized users, as well as in cases when no matching reward chain is found for the authorized user. c. Click **Next**. ![personalized reward chain](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/personalized-reward-chain.png) 11. Specify the validity period of the reward chain: a time zone, start date, and end date. To create a chain without an end date, check the **No end date** box. > [!NOTE] > To add another reward chain validity period, click **+**. If a chain has multiple validity periods, each must have an end date. The chain ends at the last second of the specified minute. For example, if an end time is set to 12:00, the chain runs until 12:00:59. > ![chain validity period](https://cdn.xsolla.net/developers/current/images/general/live-ops/chain-validity-period.svg) 12. To automatically reset the progress in the reward chain, check the **Refresh user progress after the chain ends** box. 13. If you want the reward chain to renew at a specific time, turn on the **Make reward chain renewable** toggle and specify the update schedule. > [!NOTE] > Reward chain renewal resets user progress and restarts the chain. This can only happen within the chain’s availability period. To configure auto-renewal correctly: > - Schedule it to occur no later than 15 minutes before the end of the chain’s availability period. > - Select the **No end date** checkbox if the reward chain should run indefinitely. > > **Example**: > > Reward chain availability period: March 1, 2027, 12:00 PM — March 31, 2027, 12:00 PM. The **Make reward chain renewable** toggle is enabled. > > | Auto-renewal date and time | Result | > |:----------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| > | March 31, 2027, 11:45 AM | User progress resets and the chain restarts. | > | March 31, 2027, 11:55 AM | User progress doesn't reset and the chain doesn’t restart. > > [!NOTE] > If the same value points are used in different reward chains, the user’s progress will be reset for each of them. ![renewable reward chain](https://cdn.xsolla.net/developers/current/images/guides/shop-builder/features/reward-system/renewable-reward-chain.png) 14. Click **Create**. To make a reward chain available to users, activate it. To do this: **Audience: all other audiences** 1. Open your project in Publisher Account and go to the [LiveOps > Rewards](https://publisher.xsolla.com/0/projects/0/storefront/rewards/) section. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/rewards) section. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/rewards) section. **End of audience: Premium PC games** **Audience: Web games** 1. Open your project in the account and go to the [LiveOps > Rewards](https://xsolla.com/for/web-games/account/0/projects/0/storefront/rewards) section. **End of audience: Web games** 2. In the row of the desired chain, click **•••**, then select **Activate** from the drop-down list. ### Set up via API You can use calls from the **Admin** subsection of the **Reward chains & Value points** group to manage the reward system. | Task | API call | |:----------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Create value points that grant access to rewards. | [Create value point](/api/liveops/reward-chain-value-points-admin/admin-create-value-points/). | | Assign value points to specific items. | [Set value points for items](/api/liveops/reward-chain-value-points-admin/admin-set-items-value-point-reward/). Users will receive these points after purchasing the items. | | Create a reward chain. | [Create reward chain](/api/liveops/reward-chain-value-points-admin/admin-create-reward-chain/). | | Set up reward chain validity periods. | [Create reward chain](/api/liveops/reward-chain-value-points-admin/admin-create-reward-chain/) or [Update reward chain](/api/liveops/reward-chain-value-points-admin/admin-update-reward-chain/). Pass the `periods` field as an array of objects where `date_from` defines the start, and `date_until` defines the end date of the validity period. To make the chain indefinite, specify only one period and pass `“periods[0].date_until": null`. | | Make the chain personalized. | [Create reward chain](/api/liveops/reward-chain-value-points-admin/admin-create-reward-chain/) or [Update reward chain](/api/liveops/reward-chain-value-points-admin/admin-update-reward-chain/). Pass the chain visibility conditions in the `attribute_conditions` array. You can also configure chain visibility using the `is_always_visible` parameter. The logic of the chain display will be the following: - `“is_always_visible”: true` — the chain is displayed to all users. - `“is_always_visible”: false` and the visibility conditions are specified — the chain is considered personalized and is displayed only to authorized users who meet the specified conditions. - `“is_always_visible”: false` and no visibility conditions are specified — the chain is displayed to unauthorized users, as well as in cases when no matching chain is found for the authorized user. | | Activate/deactivate the reward chain. | [Toggle reward chain](/api/liveops/reward-chain-value-points-admin/admin-toggle-reward-chain/). | | Delete the reward chain. | [Delete reward chain](/api/liveops/reward-chain-value-points-admin/admin-delete-reward-chain/). | | Resets value points and progress of all users in the reward chain. | [Reset reward chain](/api/liveops/reward-chain-value-points-admin/admin-reset-reward-chain/). After the reset, you can update the validity period of the reward chain and the user can progress through it again. ## Display reward system ### Display via site editor To ensure the reward system works correctly, user authentication must be configured. For unauthorized users, both individual and clan reward chains are displayed without progress. ![webshop reward chain](https://cdn.xsolla.net/developers/current/images/solutions/web-shop/reward-system/webshop-reward-chain.png) Authorized users who are not members of a clan see only their individual reward chain. Clan reward chains are displayed as unavailable. ![webshop clan chain](https://cdn.xsolla.net/developers/current/images/solutions/web-shop/reward-system/webshop-clan-chain.png) To display reward chains on your site: **Audience: all other audiences** 1. In your project in Publisher Account, go to the [Storefronts > Websites](https://publisher.xsolla.com/0/projects/0/site-builder) section. 2. Select your site and click **Open Site Builder**. **End of audience: all other audiences** **Audience: Free-to-play PC games** 1. Open the project in your account and go to the [Storefronts > Website](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Free-to-play PC games** **Audience: Premium PC games** 1. Open the project in your account and go to the [Storefronts > Website](https://xsolla.com/for/premium-pc-games/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Premium PC games** **Audience: Web games** 1. Open the project in your account and go to the [Storefronts > Website](https://xsolla.com/for/web-games/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Web games** **Audience: Mobile games** 1. Open the project in your account and go to the [Web Shop](https://xsolla.com/for/mobile-games/account/0/projects/0/site-builder) section. 2. Click the pane of your site. **End of audience: Mobile games** 3. If your site includes multiple pages, select the one you need: a. Click the current page title at the top of the builder. b. Select the necessary page from the drop-down list. 4. In the main area of the builder, choose a place where you want to add a new block and click **Add block**. 5. Select **Reward system** block. ![block reward system](https://cdn.xsolla.net/developers/current/images/guides/site-builder/references/blocks/block-reward-system.svg) 6. In the drop-down list, select a reward chain. ![reward system color](https://cdn.xsolla.net/developers/current/images/guides/site-builder/references/blocks/reward-system-color.png) > [!NOTE] > You can add multiple reward chains. By default, they are displayed one after another on the page. You can enable tab display in the settings and switch between reward chains by clicking the desired chain name at the top of the block. 7. Customize the button and text colors (optional). 8. To preview the chain, click **Preview** in the upper-right corner of the builder. > [!NOTE] > Preview mode is intended for testing, so the site may differ from the published version. For example, you may see inactive chains and reclaim rewards. ![reward system preview](https://cdn.xsolla.net/developers/current/images/guides/site-builder/references/blocks/reward-system-preview.png) 9. To apply the changes, publish your site: a. In the upper-right corner of the site builder, click **Publish**. b. Check the boxes next to the pages you want to publish. c. Click **Publish**. > [!NOTE] > If site publication is not available, make sure all the conditions are met: > - There are no empty sections in the builder (marked with a red dot). > - [The licensing agreement with Xsolla has been signed](/get-started/work-in-pa/legal-aspects/). > - The main page is published or selected for publication. You cannot publish child pages before the main page. > [!NOTE] > Users won’t see reward chains or reward points until the reward chain is activated, and its validity period has started. ### Value point display specifics in site editor You can select multiple reward chains within a single block and choose how they are displayed — either one below the other or in tabs. You can customize the appearance of each reward chain individually. Item cards display value points only for the reward chains that have been added to the site. However, when users purchase items, clan members receive value points for all active reward chains, regardless of whether they are displayed on the site. **Example**: You have 2 reward chains set up: one individual reward chain and one clan reward chain. The individual chain has a value point named **Crystal**, and the clan chain has a value point called **Magic Bubble**. In the item catalog, there is an item named **Sword** with assigned value points. When a clan member purchases this item, they will receive 20 **Crystals** and 40 **Magic Bubbles**. When you add the **Store** block in the builder and select the type and group of items that contain the **Sword** item: 1. If no reward chain has been added to the site, the **Sword** item will not display any value points. 2. If only an individual reward chain has been added and is active, the **Sword** item will display 20 **Crystals** only. 3. If only a clan reward chain has been added and is active, the **Sword** item will display 40 **Magic Bubbles** only. 4. If both an individual and a clan reward chain have been added and are active, the **Sword** item will display both 20 **Crystals** and 40 **Magic Bubbles**. For clan members, 40 **Magic Bubbles** will be displayed as an active value. For users without a clan, 40 **Magic Bubbles** will be displayed as a locked value. ### Display reward chains via API 1. In your application UI, implement the elements to display rewards chain steps. 2. Implement the logic to work with chains using the following client-side API calls from the **Reward chains & Value points** group: | Task | API call | |:---------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------| | Get the current user’s reward chains. | [Get current user’s reward chains](/api/liveops/reward-chain-client/get-reward-chains-list/). | | Get the current user’s value point balance. | [Get current user’s value point balance](/api/liveops/reward-chain-client/get-user-reward-chain-balance/). | | Claim the current user’s step reward from a reward chain. | [Claim step reward](/api/liveops/reward-chain-client/claim-user-reward-chain-step-reward/). | | Update a current user’s clan via user attributes. | [Update current user’s clan](/api/liveops/clan-reward-chain-client/user-clan-update/). Claims all rewards from reward chains that were not claimed for a previous clan and returns them in the response. | | Get the list of top 10 contributors to the specific reward chain under the current user’s clan. | [Get top 10 contributors to reward chain under clan](/api/liveops/clan-reward-chain-client/get-user-clan-top-contributors/). If a user doesn’t belong to a clan, the call returns an empty array. | 3. Ensure that items are correctly granted to the user. ## Set up user clan If you are not using [site builder](/liveops/promotion-tools/reward-system/#display_reward_system_via_se), you need to pass the user’s clan in Xsolla Login the user attributes for the clan reward chain to function correctly. To do this: 1. [Set up the attribute schema in Xsolla Login](/authenticate-users/login/features/user-attributes/#general_how_to_get_it). **Example of the attribute scheme in Login:** ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "description": "JSON Schema example for user attributes. Not the actual schema.", "properties": { "clan_id": { "description": "name of clan", "type": "string" }, "custom-id": { "description": "custom-id of a user.", "type": "number" }, "had_ban": { "description": "Whether the user was banned.", "type": "boolean" }, "last_purchase": { "description": "Date of user's last purchase.", "type": "string" }, }, "required": [], "title": "Example", "type": "object" } ``` 2. To add or update the `clan_id` attribute, use the [attribute update methods](/api/login/attributes-server/update-users-read-only-attributes-from-server/) and pass the `attributes` array containing objects with the `clan_id` attribute key. ```json { "user": { "id": "1234567890", "picture": "https://example.com", "name": "test-name" }, "attributes": [ { "key": "clan_id", "value": "beetles" } ] } ``` The `clan_id` attribute must be modified only on the server side, not on the client side. Therefore, when you update it by calling the [Update user attributes from server](/api/login/attributes-server/update-users-attributes-from-server) API, make sure to pass `attributes[].attr_type: “server”`. ```json { "attributes": [ { "key": "clan_id", "value": "beetles", "attr_type": "server", "permission": "private" } ], "publisher_id": 12345, "publisher_project_id": 67890 } ``` Replace `12345` and `67890` with your actual merchant ID and project ID. If you use authorization via Xsolla Login, use the [Update current user’s clan](/api/liveops/clan-reward-chain-client/user-clan-update/) API call to update the user’s clan. If the attributes contain a new clan, the user will receive any unclaimed rewards from the previous clan’s reward chain, and their clan affiliation will be updated. If the user was previously a member of a clan but is no longer part of one, their clan membership will be revoked. The response from this method includes the rewards that the user has already claimed. ### Setup specifics for Web Shop After [configuring the attribute schema](/liveops/promotion-tools/reward-system/#setup_reward_system_clan), implement passing the user’s clan data. If you use authentication by user ID, pass the user’s clan data in the response to the [User validation webhook in Web Shop](/webhooks/user-validation/user-validation-in-webshop/) webhook during authorization: * To add or refresh the `clan_id` attribute, pass an array of `attributes` objects with the `clan_id` attribute key. **Example of a webhook response:** ```json { "user": { "id": "1234567890", "picture": "https://example.com", "name": "test-name" }, "attributes": [ { "key": "clan_id", "value": "beetles" } ] } ``` * If the user has left the clan and has not joined another, pass the `clan_id` value in the `removingKeys` field. **Example of a webhook response:** ```json { "user": { "id": "1234567890", "picture": "https://example.com", "name": "test-name" }, "removingKeys": ["clan_id"] } ``` ### Setup specifics via API You can pass current attribute values directly during user authorization if you use the [Auth by custom ID](/api/login/server-custom-id/auth-by-custom-id/) API call.