Xsolla-logo

Create promo codes

post/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/promo_codes

Creates a list of promo codes with items and adds them to Backpack of the specified user. To get items created using this method, the user copies the promo code from Backpack and enters it on the gaming platform or in the game.

Securitybearer
Request
path Parameters
userId
required
string <uuid>

User ID.

merchantId
required
integer <uint32>

Merchant ID. You can find this parameter in your Publisher Account:

  • in the Project settings > Webhooks section.
  • in the Company settings > Company section.
  • in the URL in the browser address bar on any Publisher Account page. The URL has the following format: https://publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
projectId
required
integer <uint32>

Project ID. You can find this parameter in your Publisher Account next to the name of the project.

header Parameters
X-HOST-ID
required
string <uuid>

A unique header issued by Xsolla. To obtain it, please contact the integration team at integration@xsolla.com or your Customer Success Manager at csm@xsolla.com. Provide them with the project ID and merchant ID. Keep X-HOST-ID confidential, as it is part of the authentication key.

Request Body schema: application/json

A JSON object containing promo codes information.

Array (<= 100 items)
image_url
required
string

The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.

Note

An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).
item_sku
required
string

The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores.

item_name
required
string

The item's name from the Publisher Account. Currently, only English names are supported, and this information is displayed to the user in the Metaframe widget.

promo_code
required
string

Unique case sensitive code. Contains letters and numbers.

description
string

The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget.

game_name
string

The name of the game associated with the item. Refer to endpoints under the Game tag for additional details.

game_image_url
string

The URL pointing to the image representing the associated game.

external_game_id
string

The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the Game tag for additional details.

Note

It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.
Responses
201

Promo codes were successfully created.

400

Bad request.

500

Internal server error.

Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]