Coupons

How it works

Coupon promotions are a marketing tool for getting new users and increasing sales. A player who uses a coupon gets a reward that is linked to it. The reward can include:

  • virtual currency package
  • game key
  • virtual item

Every coupon has a code. To use a coupon, the user enters its code in the game, on the website, or in the mobile application.

Main features:

  • Decide the general number of coupon redemptions for one campaign.
  • Determine the number of coupon redemptions for one user in one campaign.
  • Generate codes for coupons multiple times.
  • Apply regional sale restrictions for promotions and items that are linked to a coupon.

Restrictions:

  • If you link game keys to a coupon, one of them will be emailed to a player who redeems the coupon. If there are no keys left in the campaign, the player’s request to use a coupon will be declined.
  • If the coupon includes a promotion with regional restrictions, the user from a restricted region can’t redeem it.
  • If the coupon includes an item with regional sale restrictions, the user from a restricted region can’t get the items linked to this coupon.

User flow:

  1. A user redeems a coupon.
  2. The reward that is linked to a coupon is delivered to a 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 coupon promotions.

How to get it

Prerequisites

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

Integration flow

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

Set up campaign with coupons

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

Coupon with a virtual currency package

You should specify the currency package for a virtual currency package coupon. 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 display in Store.

Coupon with a game key

You should specify a game key SKU and DRM info for a game key coupon. There are 2 options:
  • Generate coupons for the already set DRM. The parameter is set when generating coupons.
  • Choose a DRM when using a coupon.

Coupon with virtual items

You should specify the virtual item SKU and its quantity for a virtual items coupon. You can choose one or several items with different SKUs for one coupon including bundles and time-limited items.

Generating coupons

A campaign may include one or several coupons. The coupon format has 2 options:
  1. Manually entered string — suitable for a campaign with only one coupon that can be used many times (maximum is 128 characters).
  2. Generated string — line of numerals and Latin symbols (10 characters). Suits the campaign with many coupons.
You can generate coupons in the promotion editor after creating a coupon promotion. You can generate a code multiple times. Uploading the manually entered codes is made on demand via email to Xsolla.
Note
The coupon code is case sensitive. For example, winter2021 and WINTER2021 are 2 different coupons.

Regional restrictions

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

Get coupon rewards

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.

Redeem a coupon by code

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.
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: October 10, 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!