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.

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

• 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

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

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 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 and rewards 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:
• no reward
• virtual currency package
• virtual item (one or more, including bundles and time-limited items)
• game key
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.

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.

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.

Generating promo codes

• 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.

Regional restrictions

Get promo code rewards

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.

{
	"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

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

Redeem a promo code

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

selected_unit_items:{
      unit_1_sku: "selected_unit_item_sku",
      unit_2_sku: "selected_unit_item_sku"
}

Example of the response:

{
  {
    "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
    }
    ]
}

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