Skip to content
/
Get list of bundles

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

Admin

Operations

Catalog

Operations

Get list of bundlesClient-side

Request

Gets a list of bundles for building a catalog.

Attention

All projects have the limitation to the number of items that you can get in the response. The default and maximum value is 50 items per response.

Note

The use of the item catalog API calls is available without authorization, but to get a personalized catalog, you must pass the user JWT in the Authorization header.
Security
XsollaLoginUserJWT
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
localestring

Response language. Two-letter lowercase language code per ISO 639-1.

Default "en"
additional_fields[]Array of strings

The list of additional fields. These fields will be in the response if you send them in your request.

Items Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla and the process of determining the country.

Example: country=US
promo_codestring[ 1 .. 128 ] characters

Unique case sensitive code. Contains letters and numbers.

Example: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Shows time-limited items that are not available to the user. The validity period of such items has not started or has already expired.

Default 0
Example: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/bundle?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

The list of bundles was successfully received.

Bodyapplication/json
has_moreboolean(Pagination_has-more)

Used as an indicator that there are more pages.

Example: true
itemsArray of objects(Bundles_client_bundle)
Response
application/json
{
  "has_more": true,
  "items": [
    { … }
  ]
}

Get specified bundleClient-side

Request

Gets a specified bundle.

Note

This endpoint, accessible without authorization, returns generic data. However, authorization enriches the response with user-specific details for a personalized result, such as available user limits and promotions.
Security
XsollaLoginUserJWT
Path
project_idintegerrequired

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

Example: 44056
skustringrequired

Bundle SKU.

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

Unique case sensitive code. Contains letters and numbers.

Example: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Shows time-limited items that are not available to the user. The validity period of such items has not started or has already expired.

Default 0
Example: show_inactive_time_limited_items=1
additional_fields[]Array of strings

The list of additional fields. These fields will be in the response if you send them in your request.

Items Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/bundle/sku/kg_1?promo_code=WINTER2021&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

The specified bundle was successfully received.

Bodyapplication/json
item_idinteger(Bundles_item_id)[ 1 .. 255 ] characters

Internal unique item ID.

Example: 1
skustring(Bundles_sku)[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

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

Example: "bundle_1"
namestring(Bundles_client_name)

Item name.

Example: "Big Rocket"
groupsArray of objects(items_client_groups_response)

Groups the item belongs to.

Default []
Example: [{"external_id":"exclusive","name":"Exclusive"}]
descriptionstring or null(Bundles_client_description)

Item description.

Example: "Big Rocket - description."
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.

attributesArray of objects(Bundles_client-attributes)

List of attributes and their values corresponding to the item. Can be used for catalog filtering.

Default []
Example: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
typestring(Bundles_type)

Type of item.

Example: "bundle"
bundle_typestring(Bundles_bundle_type)

Bundle type. Use standard to create a bundle with items and specify the SKUs of the items included in the bundle. Use partner_side_content to create an empty bundle and add items on your side using a webhook. This type is used only for Catalog personalization on partner side.

Default "standard"
Enum"standard""partner_side_content"
Example: "standard"
image_urlstring or null(Bundles_image_url)

Image URL.

Example: "https://image.example.com"
is_freeboolean(value-is_free)

If true, the item is free.

Default false
Example: false
priceobject or null(Bundles_price)

Item price.

total_content_priceobject or null(Bundles_total_content_price)

Sum of the bundle content prices.

virtual_pricesArray of objects(Bundles_virtual_prices)

Virtual prices.

can_be_boughtboolean(Can_be_bought)

If true, the user can buy an item.

Example: true
contentArray of objects(Bundles_client_content)

Bundle package content.

Example: [{"description":"Big Rocket - short description.","image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","sku":"com.xsolla.big_rocket_1","name":"Big Rocket","type":"virtual_currency","quantity":100,"attributes":[],"is_free":false,"groups":[],"price":{"amount":"10.99","currency":"USD","amount_without_discount":"10.99"}}]
promotionsArray of objects(Catalog_item_promotions)

Applied promotions for specific items in the cart. The array is returned in the following cases:

  • A discount promotion is configured for a specific item.

  • A promo code with the Discount on selected items setting is applied.

If no item-level promotions are applied, an empty array is returned.

limitsobject or null(Catalog_item_limits_with_hourly)

Item limits.

periodsArray of objects or null(item-periods)

Item sales period.

custom_attributesobject(json)(item-custom-attributes-response)

A JSON object containing item attributes and values.

vp_rewardsArray of objects(client-item-value-point-reward)

Value point item reward.

orderinteger(Bundles_order)

Bundle's order priority in the list.

Default 1
Example: 1
media_listArray of objects(Bundles_media_list)

Bundle's additional assets.

Example: [{"type":"image","url":"https://cdn3.xsolla.com/img/misc/images/71ab1e12126f2103e1868076f0acb21a.jpg"}]
Response
application/json
{
  "item_id": 610316,
  "sku": "com.xsolla.kg_1",
  "name": "kg_10.00_bundle",
  "type": "bundle",
  "description": "pricePoint_44056_1.",
  "image_url": null,
  "long_description": null,
  "attributes": [],
  "is_free": false,
  "order": 999,
  "groups": [],
  "price": {
    "amount": "9.99",
    "currency": "USD",
    "amount_without_discount": "9.99"
  },
  "total_content_price": {
    "amount": "10.99",
    "currency": "USD",
    "amount_without_discount": "10.99"
  },
  "media_list": [],
  "virtual_prices": [],
  "promotions": [],
  "limits": {
    "per_user": { … }
  },
  "can_be_bought": true,
  "bundle_type": "standard",
  "periods": [
    { … }
  ],
  "custom_attributes": {
    "purchased": 0,
    "attr": "value"
  },
  "content": [
    { … }
  ],
  "vp_rewards": [
    { … },
    { … }
  ]
}

Get list of bundles by specified groupClient-side

Request

Gets a list of bundles within a group for building a catalog.

Attention

All projects have the limitation to the number of items that you can get in the response. The default and maximum value is 50 items per response.

Note


The use of the item catalog API calls is available without authorization, but to get a personalized catalog, you must pass the user JWT in the Authorization header.
Security
XsollaLoginUserJWT
Path
project_idintegerrequired

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

Example: 44056
external_idstringrequired

Group external ID.

Default "all"
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
localestring

Response language. Two-letter lowercase language code per ISO 639-1.

Default "en"
additional_fields[]Array of strings

The list of additional fields. These fields will be in the response if you send them in your request.

Items Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla and the process of determining the country.

Example: country=US
promo_codestring[ 1 .. 128 ] characters

Unique case sensitive code. Contains letters and numbers.

Example: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Shows time-limited items that are not available to the user. The validity period of such items has not started or has already expired.

Default 0
Example: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/bundle/group/{external_id}?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

The list of bundles was successfully received.

Bodyapplication/json
has_moreboolean(Pagination_has-more)

Used as an indicator that there are more pages.

Example: true
itemsArray of objects(Bundles_client_bundle)
Response
application/json
{
  "has_more": true,
  "items": [
    { … }
  ]
}

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