Skip to content
/
Fill cart by cart ID with...

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

Catalog API provides endpoints to manage your in-game store catalog and process purchases. Use the endpoints to configure virtual items, virtual currencies, game keys, bundles, cart and payment flows, item attributes, and import items from external sources.

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

Admin

Operations

Catalog

Operations

Virtual payment

Operations

Catalog

Operations

Entitlement

Operations

Admin

Operations

Admin

Operations

Catalog

Operations

Cart (client-side)

Operations

Cart (server-side)

Operations

Fill cart with itemsServer-side

Request

Fills the current cart with items. If the cart already has an item with the same SKU, the existing item will be replaced by the passed value.

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
localestring

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

Default "en"
Headers
x-user-forstring

User identifier can be transferred by using the Xsolla Login User JWT or the Pay Station access token.

Example: ACCESS_TOKEN/LOGIN_JWT
x-user-idstring<= 32 characters

You can use your own user ID when selling a cart with games.

Example: UNIQUE_ID
Bodyapplication/json
countrystring= 2 characters

Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla.
Example: country=US

Example: "US"
currencystring= 3 characters

The item price currency displayed in the cart. Three-letter code per ISO 4217. Check the documentation for detailed information about currencies supported by Xsolla.

Example: "USD"
itemsArray of objectsnon-emptyrequired
items[].​skustringnon-emptyrequired

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

Example: "t-shirt"
items[].​quantitynumber>= 1required

Quantity of the item.

Example: 2
curl -i -X PUT \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/catalog/v2/admin/project/44056/cart/fill?locale=en' \
  -H 'Content-Type: application/json' \
  -H 'x-user-for: ACCESS_TOKEN/LOGIN_JWT' \
  -H 'x-user-id: UNIQUE_ID' \
  -d '{
    "currency": "USD",
    "items": [
      {
        "sku": "com.xsolla.cup01",
        "quantity": 2
      },
      {
        "sku": "com.xsolla.t-shirt01",
        "quantity": 1
      },
      {
        "sku": "com.xsolla.cup01",
        "quantity": 1
      },
      {
        "sku": "com.xsolla.hat01",
        "quantity": 1
      }
    ]
  }'

Responses

The cart with items was successfully returned.

Bodyapplication/json
cart_idstring

Cart ID. Pass it to query for buy page or payment API endpoints.

Example: "cart_id"
priceobject or null

Cart price.

is_freeboolean(value-cart_is_free)

If true, a cart is free.

Default false
Example: false
itemsArray of objects
promotionsArray of objects(Catalog_cart_promotions)

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

  • A promotion affects the total cart amount, such as a promo code with the Discount on purchase setting.

  • A promotion adds bonus items to the cart.

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

warningsArray of objects
Response
application/json
{
  "cart_id": "cart_id",
  "is_free": false,
  "items": [
    { … },
    { … },
    { … }
  ],
  "warnings": [
    { … }
  ],
  "price": {
    "amount": "15.97",
    "amount_without_discount": "22.96",
    "currency": "USD"
  },
  "promotions": [
    { … }
  ]
}

Fill cart by cart ID with itemsServer-side

Request

Fills the cart by cart ID with items. If the cart already has an item with the same SKU, the existing item will be replaced by the passed value.

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
cart_idstringrequired

Cart ID.

Example: custom_id
Query
localestring

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

Default "en"
Headers
x-user-forstring

User identifier can be transferred by using the Xsolla Login User JWT or the Pay Station access token.

Example: ACCESS_TOKEN/LOGIN_JWT
x-user-idstring<= 32 characters

You can use your own user ID when selling a cart with games.

Example: UNIQUE_ID
Bodyapplication/json
countrystring= 2 characters

Two-letter uppercase country code per ISO 3166-1 alpha-2. Check the documentation for detailed information about countries supported by Xsolla.
Example: country=US

Example: "US"
currencystring= 3 characters

The item price currency displayed in the cart. Three-letter code per ISO 4217. Check the documentation for detailed information about currencies supported by Xsolla.

Example: "USD"
itemsArray of objectsnon-emptyrequired
items[].​skustringnon-emptyrequired

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

Example: "t-shirt"
items[].​quantitynumber>= 1required

Quantity of the item.

Example: 2
curl -i -X PUT \
  -u <username>:<password> \
  'https://xsolla.redocly.app/_mock/api/catalog/v2/admin/project/44056/cart/custom_id/fill?locale=en' \
  -H 'Content-Type: application/json' \
  -H 'x-user-for: ACCESS_TOKEN/LOGIN_JWT' \
  -H 'x-user-id: UNIQUE_ID' \
  -d '{
    "currency": "USD",
    "items": [
      {
        "sku": "com.xsolla.cup01",
        "quantity": 2
      },
      {
        "sku": "com.xsolla.t-shirt01",
        "quantity": 1
      },
      {
        "sku": "com.xsolla.cup01",
        "quantity": 1
      },
      {
        "sku": "com.xsolla.hat01",
        "quantity": 1
      }
    ]
  }'

Responses

The cart with items was successfully returned.

Bodyapplication/json
cart_idstring

Cart ID. Pass it to query for buy page or payment API endpoints.

Example: "cart_id"
priceobject or null

Cart price.

is_freeboolean(value-cart_is_free)

If true, a cart is free.

Default false
Example: false
itemsArray of objects
promotionsArray of objects(Catalog_cart_promotions)

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

  • A promotion affects the total cart amount, such as a promo code with the Discount on purchase setting.

  • A promotion adds bonus items to the cart.

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

warningsArray of objects
Response
application/json
{
  "cart_id": "cart_id",
  "is_free": false,
  "items": [
    { … },
    { … },
    { … }
  ],
  "warnings": [
    { … }
  ],
  "price": {
    "amount": "15.97",
    "amount_without_discount": "22.96",
    "currency": "USD"
  },
  "promotions": [
    { … }
  ]
}

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