Skip to content

Catalog API (2.0.0)

Overview

  • Version: 2.0.0
  • Servers: https://store.xsolla.com/api
  • Contact Us by Email
  • Contact URL: https://xsolla.com/
  • Required TLS version: 1.2

The Catalog API allows you to configure a catalog of in-game items on the Xsolla side and display the catalog to users in your store.

The API allows you to manage the following catalog entities:

  • Virtual items — in-game items such as weapons, skins, boosters.
  • Virtual currency — virtual money used to purchase virtual goods.
  • Virtual currency packages — predefined bundles of virtual currency.
  • Bundles — combined packages of virtual items, currency, or game keys sold as a single SKU.
  • Game keys — keys for games and DLCs distributed via platforms like Steam or other DRM providers.
  • Groups — logical groupings for organizing and sorting items within the catalog.

API calls

The API is divided into the following groups:

  • Admin — calls for creating, updating, deleting, and configuring catalog items and groups. Authenticated via basic access authentication with your merchant or project credentials. Not intended for storefront use.
  • Catalog — calls for retrieving items and building custom storefronts for end users. Designed to handle high-load scenarios. Support optional user JWT authorization to return personalized data such as user-specific limits and active promotions.
Download OpenAPI description
index.json
index.yaml
Languages
Servers
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/api/catalog/

Admin

Operations

Catalog

Operations

Virtual payment

Operations

Catalog

Operations

Entitlement

Operations

Admin

Operations

Create gameServer-sideAdmin

Request

Creates a game in the project.

Security
basicAuth
Path
project_idintegerrequired

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

Example: 44056
Bodyapplication/jsonrequired

Object with game data.

skustring[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$required

Unique item ID. The SKU may contain only lowercase and uppercase Latin alphanumeric characters, periods, dashes, and underscores.

Example: "com.xsolla.game_1"
name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)required

Object with localizations for item’s name. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character language codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

One of:

Object with localizations for item’s name. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character language codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

name.​enstring or null

English

name.​arstring or null

Arabic

name.​bgstring or null

Bulgarian

name.​cnstring or null

Chinese (Simplified)

name.​csstring or null

Czech

name.​destring or null

German

name.​esstring or null

Spanish (Spain)

name.​frstring or null

French

name.​hestring or null

Hebrew

name.​itstring or null

Italian

name.​jastring or null

Japanese

name.​kostring or null

Korean

name.​plstring or null

Polish

name.​ptstring or null

Portuguese

name.​rostring or null

Romanian

name.​rustring or null

Russian

name.​thstring or null

Thai

name.​trstring or null

Turkish

name.​twstring or null

Chinese (Traditional)

name.​vistring or null

Vietnamese

name.​kmstring or null

Khmer

name.​idstring or null

Indonesian

name.​lostring or null

Lao

name.​mystring or null

Burmese

name.​phstring or null

Filipino

name.​nestring or null

Nepali

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

Object with localizations for item’s description. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

One of:

Object with localizations for item’s description. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

Object with localizations for long description of item. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both variants for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

Any of:

Object with localizations for long description of item. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both variants for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

image_urlstring

Image URL.

Example: "http://image.png"
media_listArray of objects

Game additional assets such as screenshots, gameplay video, etc.

Example: [{"type":"image","url":"http://image.png"},{"type":"video","url":"http://video.png"}]
orderinteger

Game order priority in the list.

Example: 1
groupsArray of objects

Groups the item belongs to.

Example: ["new_games"]
attributesArray of objects(Game-Keys_admin-post-put-attributes)<= 20 items

List of attributes.

Attention. You can't specify more than 20 attributes for the item. Any attempts to exceed the limit result in an error.
is_enabledboolean

If disabled, item cannot be purchased and accessed through inventory.

Example: true
is_show_in_storeboolean

Item is available for purchase.

Example: true
unit_itemsArray of objectsrequired

Game keys for different DRMs.

Example: [{"sku":"com.xsolla.game_key_1","name":{"en-US":"Game key name","ru-RU":"Название игрового ключа"},"drm_sku":"steam_key_1","prices":[{"amount":35.5,"currency":"USD","is_enabled":true,"is_default":true}],"vc_prices":[{"amount":35.5,"sku":"com.xsolla.gold_1","is_enabled":true,"is_default":true}],"is_enabled":true,"is_free":false,"is_show_in_store":true,"pre_order":{"release_date":"2020-08-11T10:00:00+03:00","is_enabled":true,"description":"Some description"},"regions":[{"id":12},{"id":64}],"limits":{"per_user":{"total":5},"per_item":{"total":10000,"available":5000,"reserved":500,"sold":4500}},"periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}]}]
unit_items[].​skustring[ 1 .. 255 ] charactersrequired

Unique item ID. The SKU may contain only lowercase and uppercase Latin alphanumeric characters, periods, dashes, and underscores.

Example: "game_1"
unit_items[].​name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

Object with localizations for item’s name. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character language codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

One of:

Object with localizations for item’s name. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character language codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

unit_items[].​groupsArray of objects

Groups the item belongs to.

unit_items[].​attributesArray of objects(Game-Keys_admin-attributes)

List of attributes.

Example: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
unit_items[].​is_freeboolean(value-is_free)

If true, the item is free.

Default false
Example: false
unit_items[].​pricesArray of objectsrequired

Prices in real currencies.

unit_items[].​prices[].​amountnumberrequired
Example: 1299.99
unit_items[].​prices[].​currencystringrequired

Item price currency. Three-letter code per ISO 4217. Check the documentation for detailed information about currencies supported by Xsolla.

Example: "RUB"
unit_items[].​prices[].​is_defaultbooleanrequired

Default price is used to build catalog if no price in user's currency is specified.

unit_items[].​prices[].​is_enabledbooleanrequired
unit_items[].​vc_pricesArray of objects
unit_items[].​orderinteger

Game order priority in the list.

Example: 1
unit_items[].​is_enabledboolean

If disabled, item cannot be purchased and accessed through inventory.

unit_items[].​is_show_in_storeboolean

Item is available for purchase.

unit_items[].​drm_skustringrequired

DRM unique ID.

Example: "steam"
unit_items[].​pre_orderobject

Pre-order settings.

unit_items[].​regionsArray of objects(Game-Keys_regions)
unit_items[].​limitsobject(Game-key-item-limit)

Item limits.

unit_items[].​periodsArray of objects or null(item-periods)

Item sales period.

curl -i -X POST \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/items/game \
  -H 'Content-Type: application/json' \
  -d '{
    "sku": "com.xsolla.game_1",
    "name": {
      "en-US": "Game name",
      "ru-RU": "Название игры"
    },
    "description": {
      "en-US": "Game description",
      "ru-RU": "Краткое описание игры"
    },
    "long_description": {
      "en-US": "Game long description",
      "ru-RU": "Полное описание игры"
    },
    "image_url": "http://image.png",
    "media_list": [
      {
        "type": "image",
        "url": "http://image.png"
      },
      {
        "type": "video",
        "url": "http://video.png"
      }
    ],
    "groups": [
      "new_games"
    ],
    "is_enabled": true,
    "is_show_in_store": true,
    "unit_items": [
      {
        "sku": "com.xsolla.game_key_1",
        "name": {
          "en-US": "Game key name",
          "ru-RU": "Название игрового ключа"
        },
        "drm_sku": "steam_key_1",
        "prices": [
          {
            "amount": 35.5,
            "currency": "USD",
            "is_enabled": true,
            "is_default": true
          }
        ],
        "vc_prices": [
          {
            "amount": 35.5,
            "sku": "com.xsolla.gold_1",
            "is_enabled": true,
            "is_default": true
          }
        ],
        "is_enabled": true,
        "is_free": false,
        "is_show_in_store": true,
        "pre_order": {
          "release_date": "2020-08-11T10:00:00+03:00",
          "is_enabled": true,
          "description": "Some description"
        },
        "regions": [
          {
            "id": 12
          },
          {
            "id": 64
          }
        ],
        "limits": {
          "per_user": {
            "total": 5
          },
          "per_item": {
            "total": 10000,
            "available": 5000,
            "reserved": 500,
            "sold": 4500
          }
        },
        "periods": [
          {
            "date_from": "2020-08-11T10:00:00+03:00",
            "date_until": "2020-08-11T20:00:00+03:00"
          }
        ]
      }
    ]
  }'

Responses

Game was successfully created.

Bodyapplication/json
item_idinteger
Example: 101
skustring
Example: "com.xsolla.game_1"
Response
application/json
{
  "item_id": 101,
  "sku": "com.xsolla.game_1"
}

Get list of games (admin)Server-sideAdmin

Request

Gets the list of games within a project for administration. Game consists of game keys which could be purchased by a user.

Note

Do not use this endpoint for building a store catalog.
Security
basicAuth
Path
project_idintegerrequired

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

Example: 44056
Query
limitinteger>= 1

Limit for the number of elements on the page.

Example: limit=50
offsetinteger>= 0

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

Example: offset=0
promo_codestring[ 1 .. 128 ] characters

Unique case sensitive code. Contains letters and numbers.

Example: promo_code=WINTER2021
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/game?limit=50&offset=0&promo_code=WINTER2021'

Responses

The list of games was successfully received.

Bodyapplication/json
itemsArray of objects
Response
application/json
{
  "items": [
    { … },
    { … }
  ]
}

Get game (admin)Server-sideAdmin

Request

Gets a game for administration. Game consists of game keys which could be purchased by a user.

Note

Do not use this endpoint for building a store catalog.
Security
basicAuth
Path
project_idintegerrequired

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

Example: 44056
item_skustringrequired

Item SKU.

Example: booster_mega_1
Query
promo_codestring[ 1 .. 128 ] characters

Unique case sensitive code. Contains letters and numbers.

Example: promo_code=WINTER2021
curl -i -X GET \
  -u <username>:<password> \
  'https://store.xsolla.com/api/v2/project/44056/admin/items/game/sku/booster_mega_1?promo_code=WINTER2021'

Responses

Game was successfully received.

Bodyapplication/json
item_idinteger

Internal unique item ID that is provided upon item creation.

Example: 1
skustring

Unique item ID. The SKU may contain only lowercase and uppercase Latin alphanumeric characters, periods, dashes, and underscores.

Example: "game_1"
typestring

Type of item. In this case it is always unit.

Example: "unit"
name(two-letter (object or null)) or (five-letter (object or null))(name-localization-object)

Object with localizations for item’s name. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character language codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

One of:

Object with localizations for item’s name. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character language codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

description(two-letter (object or null)) or (five-letter (object or null))(description-localization-object)

Object with localizations for item’s description. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

One of:

Object with localizations for item’s description. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both options for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

long_description(two-letter (object or null)) or (five-letter (object or null))(long-description-localization-object)

Object with localizations for long description of item. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both variants for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

Any of:

Object with localizations for long description of item. Accepts value in one of two formats: two-letter lowercase language codes (e.g., en) or five-character locale codes (e.g., en-US). While both formats are accepted as input, responses return two-letter lowercase language codes. When both variants for the same language are provided (e.g., en and en-US), the last provided value is stored. You can find the full list of supported languages in the documentation.

image_urlstring

Image URL.

Example: "https://image.example.com"
media_listArray of objects

Game additional assets such as screenshots, gameplay video and so on.

Example: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
orderinteger

Game order priority in the list.

Example: 1
groupsArray of objects

Groups the item belongs to.

Example: [{"external_id":"horror","name":{"en":"Horror"}}]
attributesArray of objects(Game-Keys_admin-attributes)

List of attributes.

Example: [{"external_id":"attribute_external_id","name":{"en":"Attribute name","de":"Attributname"},"values":[{"external_id":"value_1","name":{"en":"value 1","de":"wert 1"}},{"external_id":"value_2","name":{"en":"value 2","de":"wert 2"}}]}]
is_enabledboolean
is_freeboolean(value-is_free)

If true, the item is free.

Default false
Example: false
is_show_in_storeboolean
unit_itemsArray of objects

Game keys for different DRMs.

Response
application/json
{
  "item_id": 1,
  "sku": "com.xsolla.game_1",
  "type": "unit",
  "name": {
    "en": "Game 1"
  },
  "description": {
    "en": "Example game 1"
  },
  "long_description": {
    "en": "Example game's long description"
  },
  "image_url": "https://image.example.com",
  "media_list": [
    { … }
  ],
  "order": 1,
  "groups": [
    { … }
  ],
  "attributes": [
    { … }
  ],
  "is_free": false,
  "is_enabled": true,
  "is_show_in_store": false,
  "unit_items": [
    { … },
    { … }
  ]
}

Admin

Operations

Catalog

Operations

Cart (client-side)

Operations

Cart (server-side)

Operations

Payment (client-side)

Operations

Payment (server-side)

Operations

Order

Operations

Free items

Operations

Management

Operations

Admin

Operations

Webhooks

Operations

Pre-Orders

Operations

Merchant

Operations

Catalog

This API allows getting any kind of sellable items or specific item.

Operations

Common regions

Operations

Admin

Operations