Promo codes

How it works

Promo codes are a marketing tool for attracting new users and increasing sales. After activating a promo code, the user receives one of the following reward options:

  • a discount that applies to the user’s cart or to specific items
  • one of the bonus items:
    • game key
    • virtual currency package
    • virtual item including a bundle or time-limited items

Main features:

  • choosing only a discount, only a bonus item, or both a discount and an item as a reward
  • setting the total number of redemptions of the promotional code within the campaign
  • setting the number of promo code redemptions for one user within the campaign
  • setting regional restrictions on request
  • multiple generation of promo codes
  • adding a bonus item to the cart after applying the promo code
  • applying a discount to the items after using a promo code

Restrictions:

  • only one promo code can be applied 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, a user from a region where these items are limited, will not be able to receive items using this promotional code

How it works

User flow:

  1. The user enters the promo code in the corresponding field in the UI.

  1. The cost of items is recalculated, bonus items are added.
  2. The user makes a payment, after which the promotional code is considered redeemed.
  3. 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)

Notice

You can set up different types of promotions for a game or list of games: discounts, coupons, promo codes, and bonuses.

If several promotions are valid for a game or list of games at the time of purchase, discounts are applied to the item one by one. The order in which discounts are applied does not matter.

For example:

The price of a game key is $10. In Publisher Account, the following promotions have been created for the game keys:

  • Black Friday discount promotion with a discount of 10% from November 4–30
  • Sale discount promotion with a discount of 20% from November 15 – December 15
  • promotion with a promo code for a 5% discount from November 4–30

If the game key is purchased on November 20, both discount promotions and a promotion with a promo code are valid.

The total cost of the key is then calculated as (($10 - 10%) - 20%) - 5% and will be $6.84.

When creating an order, the user can redeem a promo code and see information about the applied promotions:

  • the result of applying a discount promotion:
    • discount amount for the promotion
    • crossed out price without discount
    • discount price
  • the result of applying the bonus promotion:
    • bonus items
    • Free value in the price line for bonus items
  • the result of applying the promo code
    • discount amount for the promo code
    • crossed out price without discount
    • discount price
    • bonus items
    • Free value in the price line for bonus items

How to get it

Prerequisites

  1. Create your Xsolla Publisher Account.
  2. Connect the Game Keys module and configure it.

Integration flow

If you are implementing a quick purchase of one key using the Create order with specified item method, the user proceeds to payment without going to the cart.

At the same time, a cart is created on Xsolla's side, which is not displayed to the user. This is necessary to correctly apply all existing discounts to the user's purchase and display the amount including all discounts in the payment form.

Set up campaign with promo codes

  1. Go to Store > Promotions in Publisher Account and create a promotion.
  2. Specify the following parameters:
    1. Enter the promotion name.
    2. Choose Promo codes as the promotion type.
  3. Create an External ID — a unique promotion identifier used to manage promotions using receiving rewards and redeeming promo code methods.
  4. Specify the discount percentage for the promo code. The discount can be applied to the entire cart or to specific items.
  5. Choose the bonus items that the user receives when they redeem a promo code:
  6. Specify the total number of redemptions and number of redemptions per user.
  7. Specify the duration of the campaign.
  8. Check the settings and save the promotion.
  9. Go to the promotion editing menu.
  10. In the Codes tab, choose how the promo codes are generated.
  11. Generate the promo code or enter it manually.
  12. Save changes.
  13. Activate the promotion.

Promo code with a virtual currency package

To create a promo code with a virtual currency package:

  1. Create a virtual currency package.
  2. Specify a virtual currency package as a bonus item.

To create virtual currency package:

  1. Go to Store > Virtual Currency module settings and create a virtual currency. To do this, click New virtual currency and add:
    • image of the package (optional)
    • virtual currency SKU
    • virtual currency name
    • price of one unit of virtual currency
    • default currency
    • attribute (optional)
  2. Create the virtual currency packages. To do this, click New Package and add:
    • image of the package (optional)
    • package SKU
    • name for the package
    • short description of the package
    • virtual currency for a package
    • amount of currency in the package
    • prices in real or (and) virtual currencies
    • default currency
    • attribute (optional)
  3. Click Create package.
Note
After creating a virtual item, virtual currency, or virtual currency package, you can set statuses for the item to determine whether it is available, unavailable, or partially available.

Promo code with a virtual item

To create a promo code with a virtual item:

  1. Create a virtual item.
  2. Specify a virtual item as a bonus item.

To create virtual items:

  1. Go to Store > Virtual Items module settings and click Create Item.
  2. For each item add:
    • image (optional)
    • SKU
    • one or several groups the item should belong to (optional)
    • name of the item
    • description of the item
    • item property – consumable, nonconsumable, or time-limited items
    • prices in real or (and) virtual currencies
  3. Click Create item.
Note
After creating a virtual item, virtual currency, or virtual currency package, you can set statuses for the item to determine whether it is available, unavailable, or partially available.

You can choose one or several items with different SKUs for one promo code including bundles and time-limited items.

Promo code with a game key

To create a promo code with a game key:

  1. Create a game key package.
  2. Specify the SKU of the created game key package as a bonus and the method of choosing the platform for which the game is purchased:
    • The promo code is generated for the already set specific platform.
    • The user selects a specific platform when using promo codes.

You can choose several keys with different SKUs for one promo code.

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.

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Rate this page
Rate this page
Is there anything we can improve?

Don’t want to answer

Thank you for your feedback!
Last updated: November 28, 2023

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!