Buy Button / Promo codes
 Back to Docs
Buy Button

Promo codes

Contents

How it works

Promo codes are a marketing tool for getting new users and increasing sales. After activating the promo code and paying for the items in the cart, the user receives one of the reward options:

  • a discount that applies to the user’s cart
  • bonus items:
    • virtual currency package
    • game key
    • virtual item including a bundle or nonrenewing subscription

Main features:

  • Choose only a discount, only a bonus item, or both as a reward.
  • Decide the number of times the promo code can be used in a campaign.
  • Determine the number of promo code redemptions for one user in one campaign.
  • Set regional restrictions on demand.
  • Generate promo codes multiple times.
  • Change the list of items in the cart after using a promo code.
  • Apply the discount on the items added to the cart after using a promo code.

Restrictions:

  • Users can apply only one promo code to one cart.
  • Users can activate a promo code in the cart UI only after they add some items to the cart.
  • To get a discount or bonus, the user should pay for the items in the cart.
  • If a promo code includes an item with regional sale restrictions, the user from a restricted region can’t get the items linked to this promo code.

User flow:

  1. The user enters the promo code in the corresponding field in the cart UI.
  2. The cart’s total is recalculated.
  3. The user pays for the cart and redeems a promo code by it.
  4. If the promo code included some bonus items, they are delivered to the user in one of the following ways:
    • directly to the inventory (virtual item or a virtual currency package)
    • via email (a game key)
    • directly to the entitlement system (a game key)

Who can use it

  • Partners who have integrated one of the following products (or both):
  • Partners who want to increase sales with the help of promo codes.

How to get it

Prerequisites

  1. Create your Xsolla Publisher Account.
  2. Connect Store to your project.

Integration flow

Set up campaign with promo codes

  1. Go to Store > Promotions in Publisher Account and create a promotion.
  2. Specify necessary parameters:
    1. Enter the promotion title.
    2. Choose Promo codes as a promotion type.
  3. Choose the discount amount for a promo code.
  4. Choose the bonus product that the user receives when they redeem a promo code. Available options:
    1. No reward.
    2. Virtual currency package.
    3. Game key.
    4. Virtual item (one or several, including bundles and nonrenewing subscriptions).
  5. Decide the total number of redemptions and the number of redemptions per user.
  6. Set the campaign start and end dates.
  7. Check the settings and save the promotion.
  8. Go to the promotion editing menu.
  9. In the Codes menu, choose the method for how the promo codes are generated.
  10. Generate the promo code or enter it manually.
  11. Save changes.
  12. Activate the promotion.

Promo code with a virtual currency package

You should specify the currency package for a virtual currency package promo code. To create a virtual currency package:

  1. Go to the Virtual currency module settings and specify the following parameters:
    • Image
    • SKU
    • Currency name
    • Price of one unit of virtual currency
    • Default currency
  2. Create a required number of currency packages and specify the following parameters for every one of them:
    • Image
    • SKU
    • Name
    • Description
    • Used currency
    • Amount of currency in a package
    • Price
    • Default currency
  3. Enable the currency packages to display in Store.

Promo code with a game key

You should specify a game key SKU and DRM selection method for a game key promo code. There are 2 options:

  • Generate promo codes for the already set DRM. The parameter is set when generating promo codes.
  • Choose a DRM when using a promo code.
You can choose several keys with different SKUs for one promo code.

Promo code with a virtual item

You should specify the virtual item SKU and its quantity for a virtual items promo code. You can choose one or several items with different SKUs for one promo code including bundles and nonrenewing subscriptions.

Generating promo codes

A campaign may include one or several promo codes. The promo code format has 2 options:

  • Manually entered string — suitable for a campaign with only one promo code that can be used many times (maximum is 128 characters).
  • Generated string — line of numerals and Latin symbols (10 characters). Suits the campaign with many promo codes.
You can generate promo codes in the promotion editor after creating a promotion with promo codes. You can generate promo codes multiple times. Uploading the manually entered codes is made on demand via email to Xsolla.

Note:
The promo code is case sensitive. For example, winter2021 and WINTER2021 are 2 different promo codes.

Regional restrictions

Regional restrictions apply to the whole promotion campaign. The regional restrictions are applied on demand via email to Xsolla.

Get promo code rewards

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
  • http
{
   "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.

Redeem a promo code

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
  • http
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
  • http
{
  {
    "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.

Contents