Zum Inhalt springen
/
Create promo codes

Backpack API & Webhooks (1.0.0)

Overview

Welcome to the Backpack API, an essential tool to enhance your item-selling strategy and promotional campaigns.

With Backpack, users can store information about the items they purchased or received for free. When receiving items, users don’t need to use their game ID or go to the game from the distributor site — they can keep items in the Backpack and redeem them later.

All items purchased or received for free on the distributor website are available to the user in the Metaframe widget or Xsolla Wallet.

User flow:

  1. The user visits the distribution site.
  2. The user logs in through the Xsolla account in the Metaframe widget.
  3. The user purchases the item or gets it for free and selects the option to move the item to the Backpack.
  4. Information about the received item is transferred to the Backpack.
  5. In the Metaframe widget or Xsolla Wallet, the user opens the Backpack section and selects the item.
  6. The user receives the item.
  7. Information about the received item is transferred to the game.

Features

  • Item Storage: Users can store information about items purchased or received for free.
  • Redemption Flexibility: Items stored in the Backpack can be redeemed at the user's convenience.

Getting Started

To get started with Backpack, check out our detailed guide on Setting up Backpack. This guide will walk you through the process of configuring Backpack to suit your needs.

Key Entities

Backpack revolves around three major entities:

  1. Items: The core entities that can be distributed to users.
  2. Game: The entity designed to combine items.
  3. Backpack: The entity designed to to grant user items in the game.

Authorization

To interact with the Backpack API, you need to set up authorization.

For authorization, you have to provide 2 kinds of headers:

  1. X-HOST-ID header.
  2. Authorization header.

X-HOST-ID header

It is 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.

You can find the merchant ID 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>.

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

Note

Keep X-HOST-ID confidential, as it is part of the authentication key.

Authorization header

Set up user authentication via Xsolla account on Xsolla Wallet by following this guide. This process involves actions in the Publisher Account and assistance from our integration team.

Once the Xsolla account client is set up, use this endpoint to generate a token. The token is valid for 1 hour, after which you'll need to invoke the endpoint again for a new token.

Use the obtained token by providing the Authorization header with the Bearer token string.

Webhooks

Webhook notifications associated with the Backpack are listed under the Webhooks tag. For more in-depth information about working with webhooks, refer to our main webhook documentation.

To set up webhooks:

  1. Open your project in the Publisher Account.
  2. Click Project settings in the side menu and navigate to Webhooks.
  3. Specify the URL where you want to receive webhooks in the https://example.com format.
  4. A secret key to sign project webhooks is generated by default. To generate a new secret key, click the refresh icon.
  5. Click Enable webhooks.

If you have set up a Metaframe webhook, please contact the integration team at integration@xsolla.com or your Customer Success Manager at csm@xsolla.com. They will assist you in setting up a second webhook for the project.

OpenAPI-Beschreibung herunterladen
index.json
index.yaml
Sprachen
Server
Mock server
https://xsolla.redocly.app/_mock/de/api/backpack/
https://metaframe.xsolla.com/

Game

Operations related to creating and updating game entities. Game entities are used to combine and sort items.

Operationen

Items

Operations for creating, managing, and distributing items to users via Backpack. Items are the core entities associated with games.

Operationen

Create game keys

Anfrage

Creates a list of game keys and adds them to Backpack of the specified user.

Sicherheit
bearer
Pfad
userIdstring(uuid)erforderlich

User ID.

merchantIdinteger(uint32)erforderlich

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

  • 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>.
projectIdinteger(uint32)erforderlich

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

Header
X-HOST-IDstring(uuid)erforderlich

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.

Bodyapplication/json

A JSON object containing game keys information.

Array [
descriptionstring

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.

image_urlstringerforderlich

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_skustringerforderlich

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

codestringerforderlich

The game key associated with the item.

game_namestring

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

game_image_urlstring

The URL pointing to the image representing the associated game. Refer to endpoints under the Game tag for additional details.

external_game_idstring

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.
]
curl -i -X POST \
  'https://xsolla.redocly.app/_mock/de/api/backpack/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/game_keys' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-HOST-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '[
    {
      "description": "string",
      "image_url": "string",
      "item_sku": "string",
      "code": "string",
      "game_name": "string",
      "game_image_url": "string",
      "external_game_id": "string"
    }
  ]'

Antworten

Game keys were successfully created.

Bodyapplication/jsonArray [
item_idstring(uuid)erforderlich

The unique identifier for the item.

descriptionstring or null

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.

image_urlstringerforderlich

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_skustringerforderlich

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

codestringerforderlich

The game key associated with the item.

game_namestringerforderlich

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

external_game_idstringerforderlich

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

The item type indicates the category of claimed item. In this case, the item type will be game key.

Wert"game_key"
created_atstringerforderlich

The timestamp indicates the moment in which the item is claimed by user.

item_statusstringerforderlich

The item status shows stage of item. In this case, the item status will be claimed.

]
Antwort
application/json
[
  {
    "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
    "description": "string",
    "image_url": "string",
    "item_sku": "string",
    "code": "string",
    "game_name": "string",
    "external_game_id": "string",
    "item_type": "game_key",
    "created_at": "string",
    "item_status": "string"
  }
]

Create promo codes

Anfrage

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.

Sicherheit
bearer
Pfad
userIdstring(uuid)erforderlich

User ID.

merchantIdinteger(uint32)erforderlich

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

  • 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>.
projectIdinteger(uint32)erforderlich

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

Header
X-HOST-IDstring(uuid)erforderlich

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.

Bodyapplication/json

A JSON object containing promo codes information.

Array [
item_skustringerforderlich

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_namestringerforderlich

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.

image_urlstringerforderlich

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).
descriptionstring

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.

promo_codestringerforderlich

Unique case sensitive code. Contains letters and numbers.

game_namestring

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

game_image_urlstring

The URL pointing to the image representing the associated game.

external_game_idstring

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.
]
curl -i -X POST \
  'https://xsolla.redocly.app/_mock/de/api/backpack/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/promo_codes' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-HOST-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '[
    {
      "item_sku": "string",
      "item_name": "string",
      "image_url": "string",
      "description": "string",
      "promo_code": "string",
      "game_name": "string",
      "game_image_url": "string",
      "external_game_id": "string"
    }
  ]'

Antworten

Promo codes were successfully created.

Bodyapplication/jsonArray [
item_idstring(uuid)erforderlich

The unique identifier for the item.

descriptionstring or null

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.

image_urlstringerforderlich

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_skustringerforderlich

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

game_namestringerforderlich

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

external_game_idstringerforderlich

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

The item type indicates the category of claimed item. In this case, the item type will be promo code.

Wert"promo_code"
created_atstringerforderlich

The timestamp indicates the moment in which the item is claimed by user.

item_statusstringerforderlich

The item status shows stage of item. In this case, the item status will be claimed.

item_namestringerforderlich

The item name in the Publisher Account.

project_idinteger(uint32)erforderlich

The Publisher Account project ID associated with the item.

merchant_idinteger(uint32)erforderlich

The Publisher Account ID associated with the item.

]
Antwort
application/json
[
  {
    "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
    "description": "string",
    "image_url": "string",
    "item_sku": "string",
    "game_name": "string",
    "external_game_id": "string",
    "item_type": "promo_code",
    "created_at": "string",
    "item_status": "string",
    "item_name": "string",
    "project_id": 0,
    "merchant_id": 0
  }
]

Create virtual currency

Anfrage

Creates a list of virtual currency packages and adds them to Backpack of the specified user.

Sicherheit
bearer
Pfad
userIdstring(uuid)erforderlich

User ID.

merchantIdinteger(uint32)erforderlich

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

  • 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>.
projectIdinteger(uint32)erforderlich

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

Header
X-HOST-IDstring(uuid)erforderlich

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.

Bodyapplication/json

A JSON object containing virtual currency packages information.

Array [
item_skustringerforderlich

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_namestringerforderlich

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.

image_urlstringerforderlich

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).
descriptionstring

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.

pricenumbererforderlich

The price of the virtual currency item in the specified currency (currency parameter). This value represents the cost of acquiring the specified amount of virtual currency. For example, if the price is 10.99 and the currency is USD, it means the cost to obtain the associated amount of virtual currency is $10.99.

currencystringerforderlich

The currency which prices are displayed in (USD by default). Three-letter currency code per ISO 4217.

quantityinteger(uint32)erforderlich

The quantity for the virtual currency package.

game_namestring

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

game_image_urlstring

The URL pointing to the image representing the associated game.

external_game_idstring

The external identifier uniquely assigned by you to represent the game.

platformstring(Platform)

The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.

Wert"steam"
]
curl -i -X POST \
  'https://xsolla.redocly.app/_mock/de/api/backpack/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/virtual_currency' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-HOST-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '[
    {
      "item_sku": "string",
      "item_name": "string",
      "image_url": "string",
      "description": "string",
      "price": 0,
      "currency": "string",
      "quantity": 0,
      "game_name": "string",
      "game_image_url": "string",
      "external_game_id": "string",
      "platform": "steam"
    }
  ]'

Antworten

Virtual currencies were successfully created.

Bodyapplication/jsonArray [
item_idstring(uuid)erforderlich

The unique identifier for the item.

descriptionstring or null

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.

image_urlstringerforderlich

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_skustringerforderlich

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

game_namestringerforderlich

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

external_game_idstringerforderlich

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

The item type indicates the category of claimed item. In this case, the item type will be virtual currency.

Wert"virtual_currency"
created_atstringerforderlich

The timestamp indicates the moment in which the item is claimed by user.

item_statusstringerforderlich

The item status shows stage of item. In this case, the item status will be claimed.

item_namestringerforderlich

The item name in the Publisher Account.

platformstringerforderlich

The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.

Wert"steam"
project_idinteger(uint32)erforderlich

The Publisher Account project ID associated with the item.

merchant_idinteger(uint32)erforderlich

The Publisher Account ID associated with the item.

pricenumbererforderlich

The price for the item.

currencystringerforderlich

The currency for the item price.

quantityinteger(uint32)erforderlich

The quantity for the virtual currency package.

is_external_vcbooleanerforderlich

An indication to show whether this item is created under Publisher Account.

]
Antwort
application/json
[
  {
    "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
    "description": "string",
    "image_url": "string",
    "item_sku": "string",
    "game_name": "string",
    "external_game_id": "string",
    "item_type": "virtual_currency",
    "created_at": "string",
    "item_status": "string",
    "item_name": "string",
    "platform": "steam",
    "project_id": 0,
    "merchant_id": 0,
    "price": 0,
    "currency": "string",
    "quantity": 0,
    "is_external_vc": true
  }
]

Create virtual items

Anfrage

Creates a list of virtual items and adds them to Backpack of the specified user.

Sicherheit
bearer
Pfad
userIdstring(uuid)erforderlich

User ID.

merchantIdinteger(uint32)erforderlich

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

  • 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>.
projectIdinteger(uint32)erforderlich

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

Header
X-HOST-IDstring(uuid)erforderlich

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.

Bodyapplication/json

A JSON object containing virtual items information.

Array [
item_skustringerforderlich

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_namestringerforderlich

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.

image_urlstringerforderlich

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).
descriptionstring

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_namestring

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

game_image_urlstring

The URL pointing to the image representing the associated game.

external_game_idstring

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.
platformstring(Platform)

The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.

Wert"steam"
]
curl -i -X POST \
  'https://xsolla.redocly.app/_mock/de/api/backpack/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/virtual_items' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-HOST-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -d '[
    {
      "item_sku": "string",
      "item_name": "string",
      "image_url": "string",
      "description": "string",
      "game_name": "string",
      "game_image_url": "string",
      "external_game_id": "string",
      "platform": "steam"
    }
  ]'

Antworten

Virtual items were successfully created.

Bodyapplication/jsonArray [
item_idstring(uuid)erforderlich

The unique identifier for the item.

descriptionstring or null

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.

image_urlstringerforderlich

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_skustringerforderlich

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

game_namestringerforderlich

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

external_game_idstringerforderlich

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

The item type indicates the category of claimed item. In this case, the item type will be virtual currency.

Wert"virtual_currency"
created_atstringerforderlich

The timestamp indicates the moment in which the item is claimed by user.

item_statusstringerforderlich

The item status shows stage of item. In this case, the item status will be claimed.

item_namestringerforderlich

The item name in the Publisher Account.

platformstringerforderlich

The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.

Wert"steam"
project_idinteger(uint32)erforderlich

The Publisher Account project ID associated with the item.

merchant_idinteger(uint32)erforderlich

The Publisher Account ID associated with the item.

]
Antwort
application/json
[
  {
    "item_id": "4d8cd62e-a579-4dae-af8c-3172f96f8f7c",
    "description": "string",
    "image_url": "string",
    "item_sku": "string",
    "game_name": "string",
    "external_game_id": "string",
    "item_type": "virtual_currency",
    "created_at": "string",
    "item_status": "string",
    "item_name": "string",
    "platform": "steam",
    "project_id": 0,
    "merchant_id": 0
  }
]

Get user's Backpack items

Anfrage

Returns the list of items from Backpack of a specified user. Items can be game keys, virtual items, and virtual currency.

Sicherheit
bearer
Pfad
merchantIdinteger(uint32)erforderlich

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

  • 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>.
projectIdinteger(uint32)erforderlich

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

userIdstring(uuid)erforderlich

User ID.

Abfrage
offsetinteger(uint32)

Number of the element from which the list is generated (the count starts from 0).

limitinteger(uint32)

Limit for the number of elements on the page. If not specified, all items are returned (default).

Header
X-HOST-IDstring(uuid)erforderlich

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.

curl -i -X GET \
  'https://xsolla.redocly.app/_mock/de/api/backpack/web/backpack/merchants/{merchantId}/projects/{projectId}/users/{userId}/items?offset=0&limit=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-HOST-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Antworten

The list of items from users's Backpack was succesfully recieved.

Bodyapplication/jsonArray [
item_idstringerforderlich

The unique identifier for the item. Specified when creating item via API call.

item_skustringerforderlich

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_namestringerforderlich

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.

image_urlstringerforderlich

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).
image_proxy_urlstring or nullerforderlich

The URL pointing to the image of the item in the proxy storage, which is displayed to the player in the Metaframe widget. This URL allows you to resize the image by passing the dimensions to the URL as parameters.

descriptionstring or null

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.

project_idinteger(uint32)erforderlich

The Publisher Account project ID associated with the item.

merchant_idinteger(uint32)erforderlich

The Publisher Account ID associated with the item.

item_typestringerforderlich

The item type indicates the category of claimed item.

Enum"game_key""promo_code""virtual_item""virtual_currency"
pricenumbererforderlich

The price of the virtual currency item in the specified currency (currency parameter). This value represents the cost of acquiring the specified amount of virtual currency. For example, if the price is 10.99 and the currency is USD, it means the cost to obtain the associated amount of virtual currency is $10.99.

currencystringerforderlich

The currency which prices are displayed in (USD by default). Three-letter currency code per ISO 4217.

Standard "USD"
promo_codestringerforderlich

Unique case sensitive code that user can redeem in the game to recieve the item. Contains letters and numbers.

codestringerforderlich

The game key associated with the item.

game_namestringerforderlich

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

external_game_idstringerforderlich

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

The timestamp indicates the moment in which the item is claimed by user.

item_statusstringerforderlich

The item status shows stage of item. In this case, the item status will be claimed.

quantityinteger(uint32)erforderlich

Item quantity.

is_external_vcbooleanerforderlich

Whether the virtual currency is partners' currency or Xsolla currency.

platformstring(Platform)erforderlich

The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.

Wert"steam"
]
Antwort
application/json
[
  {
    "item_id": "string",
    "item_sku": "string",
    "item_name": "string",
    "image_url": "string",
    "image_proxy_url": "string",
    "description": "string",
    "project_id": 0,
    "merchant_id": 0,
    "item_type": "game_key",
    "price": 0,
    "currency": "USD",
    "promo_code": "string",
    "code": "string",
    "game_name": "string",
    "external_game_id": "string",
    "created_at": "string",
    "item_status": "string",
    "quantity": 0,
    "is_external_vc": true,
    "platform": "steam"
  }
]

Delete item from Backpack

Anfrage

Deletes the specified item from Backpack of the specified user.

Sicherheit
bearer
Pfad
merchantIdinteger(uint32)erforderlich

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

  • 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>.
projectIdinteger(uint32)erforderlich

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

userIdstring(uuid)erforderlich

User ID.

itemIdstring(uuid)erforderlich

The unique identifier for the item. Specified when creating item via API call.

Header
X-HOST-IDstring(uuid)erforderlich

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.

curl -i -X DELETE \
  'https://xsolla.redocly.app/_mock/de/api/backpack/web/backpack/merchants/{merchantId}/projects/{projectId}/users/{userId}/items/{itemId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'X-HOST-ID: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Antworten

No content

Antwort
Kein Inhalt

Webhooks

Various events and notifications related to Backpack functionality, such as player validations and item redemptions.

Webhooks

Backpack

Endpoints for granting users items from their Backpack, including game keys, virtual items, and virtual currency.

Operationen