Skip to content

Shop Builder 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

Shop Builder API provides a third-party solution for implementing the server side for your store interface. Use the endpoints to manage in-game items, in-game currencies, cart, player inventory, promotions, game library, etc.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Mock server
https://xsolla.redocly.app/_mock/api/shop-builder/
https://store.xsolla.com/api/

Admin

Operations

Personalized catalog

This API allows to specify rules for user attributes. If the user meets all conditions for a concrete rule, personalized items will be shown.

For personalized promotions see Promotions section.

To pass attributes before a purchase, you can use Xsolla Login API or pass them into user.attributes property while generating token using Pay Station API.

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://xsolla.redocly.app/_mock/api/shop-builder/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://xsolla.redocly.app/_mock/api/shop-builder/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://xsolla.redocly.app/_mock/api/shop-builder/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

Webhooks

Operations

Pre-Orders

Operations

Merchant

Operations

Catalog

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

Operations

Common regions

Operations

Catalog

Operations

Entitlement

Operations

Admin

Operations

Common

Operations

Coupons

This API allows to you to manage coupons.

Operations

Promo codes

This API allows to manage promo codes.

Operations

Unique catalog offers

This API allows to you to manage unique catalog offers.

Operations

Discounts

This API allows to you to manage discount promotions.

Operations

Bonuses

This API allows to manage bonus promotions.

Operations

Admin

Operations

Catalog

Operations

Virtual payment

Operations

Management

Operations

Admin

Operations

Client

Operations

Clans client

Operations

Admin

Operations

Client

Operations

Admin

Operations

Client

Operations

Admin

Operations

Client

Operations

Admin

Operations