Set up promotional campaigns

After you integrate the store into the game, you can set up coupons, promo codes, bonuses, or discount promotions to attract new users and increase sales.

You can also run personalized promotions, that is, set up campaigns for the specific users. You can set the number of items available to the user for the promotion. This is only possible for promotional campaigns with discounts and promotional campaigns with bonuses.

Notice
You can use a personalized catalog with the Login product only.

If you have been integrated with the Login product already, do these before setting up personalized promotions for users:

  1. Set up user attributes for your project.
  2. Set user attributes schema in the Login section.

Attributes are user features that are stored as key-value pairs. With the help of the attributes you can:

  • segment users
  • prepare personal storefronts for each group of users in your Web Shop.

To ensure the integrity of transmitted data, you can set attribute validation rules in JSON Schema format in Publisher Account, and manage user attributes using Login API methods or webhooks. You can also edit the attributes values in your Publisher Account. For more information, refer to How-to set up user attributes.

Coupons have codes that grant free items without any purchase or shopping cart. To use a coupon, a user should enter the code in the game, website, or mobile application. The linked reward is then delivered to the user’s inventory. Rewards can include:

See the Coupons section for more information about coupons.

Promo codes apply a discount to the shopping cart or add free items to the cart during checkout. After activating the promo code and paying for the items in the cart, the user can receive one of the following rewards:

See the Promo codes section for more information about promo codes.

Users can also receive a bonus when buying promotional items. Bonuses can include:

A discount promotion allows you to set up a discount on one or more products. An unlimited number of promotions can be applied to one product. Discounts are not cumulative, but are applied to the cost of individual item. Discounts can apply to one or several of the following items:

See the Discount promotions section for more information about discounts.

Promotional campaign with coupons

To start a promotional campaign with coupons:

  1. Set up a promotional campaign with coupons.
  2. Use the methods of coupon redemption by code.
  3. Use the methods of getting a coupon reward.

Note
Regional restrictions apply to the whole promotion campaign. You can email Xsolla to apply regional restrictions.

Set up a promotional campaign with coupons

  1. Open your project in Publisher Account.
  2. Click Store in the side menu and go to Promotions.
  3. Click Create promotion.
  4. Specify the following parameters:
    1. Enter the promotion title.
    2. Choose Coupons as the promotion type.
  5. Choose the reward that the user receives when they redeem a coupon. Available options:
  6. Add:
    1. Promotional identifier in External ID.
    2. Bonus items that the user receives when they redeem a coupon.
    3. Item’s type and amount.
  7. Click Next.
  8. Specify the total number of redemptions and the number of redemptions per user.
  9. Set the campaign start and end dates.
  10. Click Next.
  11. Check the settings and click Save and exit.

Note
Promotion bonuses and terms cannot be changed once your promotion is live.

  1. Click Store in the side menu and go to Promotions.
  2. Select the promotion, click the ••• menu button to open a menu and click Edit plan.
  3. Go to the Codes tab.
  4. Specify how coupons are generated.
  5. Generate the coupon code or enter it manually.
  6. Activate the promotion.

Redeem a coupon by code

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the call of the Redeem coupon code method to use a coupon. Depending on the is_selectable parameter value in the Get coupon rewards method response, there are 2 possible flows:

  1. If is_selectable=true, you should pass the selected_unit_items object in the following format when calling the Redeem coupon code method:

Copy
Full screen
Small screen
selected_unit_items:{
      unit_1_sku: "selected_unit_item_sku",
      unit_2_sku: "selected_unit_item_sku"
}

Example of the response:

Copy
Full screen
Small screen
{
  {
    "items": [
    {
      "sku": "xsollus_gold_edition_steam",
      "name": "Xsollus: Gold Edition (steam)",
      "type": "game_key",
      "description": null,
      "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/9541470622d96a821a9a11ea7763ea4c.png",
      "attributes": [],
      "is_free": true,
      "groups": [],
      "price": null,
      "virtual_prices": [],
      "drm_name": "Steam",
      "drm_sku": "steam",
      "has_keys": false,
      "is_pre_order": true,
      "release_date": null,
      "quantity": 1
    },
    {
      "sku": "xsollus_bonus_pack_edition_origin",
      "name": "Xsollus: Bonus Pack (origin)",
      "type": "game_key",
      "description": null,
      "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/aa2efd78dfd4e5dda5293f8c8e49af6d.png",
      "attributes": [],
      "is_free": true,
      "groups": [],
      "price": null,
      "virtual_prices": [],
      "drm_name": "Origin",
      "drm_sku": "origin",
      "has_keys": false,
      "is_pre_order": true,
      "release_date": null,
      "quantity": 3
  }
  ]
}

  1. If is_selectable=false, you shouldn’t pass additional parameters in the request.

Get coupon rewards

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the call of the Get coupon rewards method to get the list of items that the user receives after redeeming a coupon. Depending on the is_selectable parameter value in the response, there are 2 possible flows:

  1. If the is_selectable=true value, you should show the form for choosing elements from the unit_items object for every item with type=unit element. In this form, the user chooses only one element for each unit type.
Example of the response:

Copy
Full screen
Small screen
{
   "bonus": [{
       "item": {
           "sku": "xsollus_gold_edition",
           "name": "Xsollus: Gold Edition",
           "type": "unit",
           "description": null,
           "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/9541470622d96a821a9a11ea7763ea4c.png",
           "unit_items": [{
               "sku": "xsollus_gold_edition_steam",
               "name": "Xsollus: Gold Edition (steam)",
               "type": "game_key",
               "drm_name": "Steam",
               "drm_sku": "steam"
           }, {
               "sku": "xsollus_gold_edition_playstation",
               "name": "Xsollus: Gold Edition (playstation)",
               "type": "game_key",
               "drm_name": "Playstation",
               "drm_sku": "playstation"
           }, {
               "sku": "xsollus_gold_edition_xbox",
               "name": "Xsollus: Gold Edition (xbox)",
               "type": "game_key",
               "drm_name": "XBox",
               "drm_sku": "xbox"
           }, {
               "sku": "xsollus_gold_edition_rockstar",
               "name": "Xsollus: Gold Edition (rockstar)",
               "type": "game_key",
               "drm_name": "Rockstar Games Launcher",
               "drm_sku": "rockstar"
           }]
       },
       "quantity": 1
   }, {
       "item": {
           "sku": "xsollus_bonus_pack_edition",
           "name": "Xsollus: Bonus Pack",
           "type": "unit",
           "description": null,
           "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/aa2efd78dfd4e5dda5293f8c8e49af6d.png",
           "unit_items": [{
               "sku": "xsollus_bonus_pack_edition_steam",
               "name": "Xsollus: Bonus Pack (steam)",
               "type": "game_key",
               "drm_name": "Steam",
               "drm_sku": "steam"
           }, {
               "sku": "xsollus_bonus_pack_edition_playstation",
               "name": "Xsollus: Bonus Pack (playstation)",
               "type": "game_key",
               "drm_name": "Playstation",
               "drm_sku": "playstation"
           }, {
               "sku": "xsollus_bonus_pack_edition_xbox",
               "name": "Xsollus: Bonus Pack (xbox)",
               "type": "game_key",
               "drm_name": "XBox",
               "drm_sku": "xbox"

           }]
       },
       "quantity": 3
   }],
   "is_selectable": true

  1. If is_selectable=false, you shouldn’t pass additional parameters in the request.

Promotional campaign with promo codes

To start a promotional campaign with promo codes:

  1. Set up a promotional campaign with promo codes.
  2. Implement the methods of promo code redemption.
  3. Implement the method of getting a promo code reward.

Set up a promotional campaign with promo codes

  1. Open your project in Publisher Account.
  2. Click Store in the side menu and go to Promotions.
  3. Click Create promotion.
  4. Specify the following parameters:
    1. Enter the promotion title.
    2. Choose Promo code as the promotion type.
  5. Choose what the user receives when they redeem a promo code: no reward, discount on all items in the cart, discount on specific items, bonus items, or a combination.
  6. Set the discount amount.
  7. Click Next.
  8. Specify the total number of redemptions and the number of redemptions per user.
  9. Click Next.
  10. Set the campaign start and end dates.
  11. Click Next.
  12. Check the settings and click Save and exit.

Note
Promotion bonuses and terms cannot be changed once your promotion is live.

  1. Click Store in the side menu and go to Promotions.
  2. Select the promotion, click the ••• menu button to open a menu and click Edit plan.
  3. Go to the Codes tab.
  4. Specify how promo codes are generated.
  5. Generate the promo code or enter it manually.
  6. Activate the promotion.

Redeem a promo code

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the call of the Redeem promo code method to use a promo code. Depending on the is_selectable parameter value, there are 2 possible flows in the Get promo code rewards method response:

  1. If is_selectable=true, you should pass the selected_unit_items object in the following format when calling the Redeem promo code method:

Copy
Full screen
Small screen
selected_unit_items:{
      unit_1_sku: "selected_unit_item_sku",
      unit_2_sku: "selected_unit_item_sku"
}

Example of the response:

Copy
Full screen
Small screen
{
  {
    "items": [
    {
      "sku": "xsollus_gold_edition_steam",
      "name": "Xsollus: Gold Edition (steam)",
      "type": "game_key",
      "description": null,
      "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/9541470622d96a821a9a11ea7763ea4c.png",
      "attributes": [],
      "is_free": true,
      "groups": [],
      "price": null,
      "virtual_prices": [],
      "drm_name": "Steam",
      "drm_sku": "steam",
      "has_keys": false,
      "is_pre_order": true,
      "release_date": null,
      "quantity": 1
    },
    {
      "sku": "xsollus_bonus_pack_edition_origin",
      "name": "Xsollus: Bonus Pack (origin)",
      "type": "game_key",
      "description": null,
      "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/aa2efd78dfd4e5dda5293f8c8e49af6d.png",
      "attributes": [],
      "is_free": true,
      "groups": [],
      "price": null,
      "virtual_prices": [],
      "drm_name": "Origin",
      "drm_sku": "origin",
      "has_keys": false,
      "is_pre_order": true,
      "release_date": null,
      "quantity": 3
    }
    ]
}

  1. If is_selectable=false, you shouldn’t pass additional parameters in the request.

Get promo code rewards

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the call of the Get promo code rewards method to get the list of items that the user receives after redeeming a promo code. Depending on the is_selectable parameter value in the response, there are 2 possible flows:

  1. If the is_selectable=true value, you should show the form for choosing elements from the unit_items object for every item with type=unit element. In this form, the user chooses only one element for each unit type.
Example of the response:

Copy
Full screen
Small screen
{
   "bonus": [{
       "item": {
           "sku": "xsollus_gold_edition",
           "name": "Xsollus: Gold Edition",
           "type": "unit",
           "description": null,
           "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/9541470622d96a821a9a11ea7763ea4c.png",
           "unit_items": [{
               "sku": "xsollus_gold_edition_steam",
               "name": "Xsollus: Gold Edition (steam)",
               "type": "game_key",
               "drm_name": "Steam",
               "drm_sku": "steam"
           }, {
               "sku": "xsollus_gold_edition_playstation",
               "name": "Xsollus: Gold Edition (playstation)",
               "type": "game_key",
               "drm_name": "Playstation",
               "drm_sku": "playstation"
           }, {
               "sku": "xsollus_gold_edition_xbox",
               "name": "Xsollus: Gold Edition (xbox)",
               "type": "game_key",
               "drm_name": "XBox",
               "drm_sku": "xbox"
           }, {
               "sku": "xsollus_gold_edition_nintendo_eshop",
               "name": "Xsollus: Gold Edition (nintendo_eshop)",
               "type": "game_key",
               "drm_name": "Nintendo Switch eShop",
               "drm_sku": "nintendo_eshop"
           }]
       },
       "quantity": 1
   }, {
       "item": {
           "sku": "xsollus_bonus_pack_edition",
           "name": "Xsollus: Bonus Pack",
           "type": "unit",
           "description": null,
           "image_url": "https:\/\/cdn3.xsolla.com\/img\/misc\/images\/aa2efd78dfd4e5dda5293f8c8e49af6d.png",
           "unit_items": [{
               "sku": "xsollus_bonus_pack_edition_steam",
               "name": "Xsollus: Bonus Pack (steam)",
               "type": "game_key",
               "drm_name": "Steam",
               "drm_sku": "steam"
           }, {
               "sku": "xsollus_bonus_pack_edition_origin",
               "name": "Xsollus: Bonus Pack (origin)",
               "type": "game_key",
               "drm_name": "Origin",
               "drm_sku": "origin"
           }, {
               "sku": "xsollus_bonus_pack_edition_drmfree",
               "name": "Xsollus: Bonus Pack (drmfree)",
               "type": "game_key",
               "drm_name": "DRM Free",
               "drm_sku": "drmfree"
           }, {
               "sku": "xsollus_bonus_pack_edition_gog",
               "name": "Xsollus: Bonus Pack (gog)",
               "type": "game_key",
               "drm_name": "GOG",
               "drm_sku": "gog"
           }, {
               "sku": "xsollus_bonus_pack_edition_rockstar",
               "name": "Xsollus: Bonus Pack (rockstar)",
               "type": "game_key",
               "drm_name": "Rockstar Games Launcher",
               "drm_sku": "rockstar"
           }]
       },
       "quantity": 3
   }],
   "discount": {
       "percent": null
   },
   "is_selectable": true

  1. If is_selectable=false, you shouldn’t pass additional parameters in the request.

Promotional campaign with bonuses

To start a promotional campaign with a bonus:

  1. Open your project in Publisher Account.
  2. Click Store in the side menu and go to Promotions.
  3. Click Create promotion.
  4. Specify the following parameters:
    1. Enter the promotion title.
    2. Choose Bonus as a promotion type.
  5. Choose promotional items.
  6. Choose items granted to users when they purchase promotional items.
  7. Click Next.
  8. If you want to set up promotion for specific users, switch the Trigger promotion only for specific users toggle to On and specify the condition(s).
  9. If you want to limit the availability of a promotion to specific users, switch the Limit number of times one user can use promotion toggle to On and specify the number.
  10. Click Next.
  11. Set the campaign start and end dates.
  12. Click Next.
  13. Check the settings and click Save and exit.

Note
Promotion bonuses and terms cannot be changed once your promotion is live.

  1. Click Store in the side menu and go to Promotions.
  2. Select the promotion, click the ••• menu button to open a menu and click Edit plan.
  3. Activate the promotion.

Promotional campaign with discounts

Note
You can’t apply regional restrictions to discount promotions.

Set up a promotional campaign with discounts via Publisher Account

To start a promotional campaign with a discount:

  1. Open your project in Publisher Account.
  2. Click Store in the side menu and go to Promotions.
  3. Click Create promotion.
  4. Specify the following parameters:
    1. Enter the promotion title.
    2. Choose Discount as a promotion type.
  5. Set up discounts that apply to one or several items.
  6. Set the discount amount.
  7. Click Next.
  8. If you want to set up promotion for specific users, switch the Trigger promotion only for specific users toggle to On and specify the condition(s).
  9. If you want to limit the availability of a promotion to specific users, switch the Limit number of times one user can use promotion toggle to On and specify the number.
  10. Click Next.
  11. Set the campaign start and end dates.
  12. Click Next.
  13. Check the settings and click Save and exit.

Note
Promotion bonuses and terms cannot be changed once your promotion is live.

  1. Click Store in the side menu and go to Promotions.
  2. Select the promotion, click the ••• menu button to open a menu and click Edit plan.
  3. Activate the promotion.

Set up a promotional campaign with discounts via API

To work with discount promotions, you can use the methods from the Discount subsection from the Promotions method group.

To create the promotion via API methods:

  1. Call the Create discount promotion for item method with required parameters.
  2. Call the Update item promotion method with the “is_enabled”:true parameter to activate the promotion.

To edit the promotion via an API, call the Update item promotion method with new promotion parameters. You can also edit the promotion that has the Active status.

When creating or editing a discount promotion via API methods, you can also:

Your progress
Thank you for your feedback!
Last updated: August 8, 2022

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!