Automatic catalog update via API

You can automate the creation and updating of the catalog with In-Game Store API calls. With automation, you can keep your catalog up to date without spending a lot of time on it. Catalog automate allows you to create and update items and promotions and import data from external systems.

This reduces the time it takes to maintain and update:

• catalogs that contain a lot of items
• promotions of any type
• country-based prices

Basic authorization is used for API calls to create and update items and promotions. Pass the Authorization:Basic <your_authorization_basic_key>, where <your_authorization_basic_key> is the merchant ID:API key pair encoded according to the Base64 standard. Go to Publisher Account to find these parameters:

• Merchant ID is shown:
  • 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>.

• API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
  • Company settings > API keys
  • Project settings > API keys

Create and update items

If you need to create numerous items, you can create a script that calls the API method of the required item type the necessary number of times.

Virtual items

To update the catalog:

1. Get data from the catalog with the Get virtual item or Get all virtual items list API methods.
2. Pass new parameter values with the Update virtual item API method.

To create virtual items, use the Create virtual item API method.

Bundles

To update the catalog:

1. Get data from the catalog with the Get list of bundles API method.
2. Pass new parameter values with the Update bundle API method.

To create a bundle, use the Create bundle API method.
If you want to add game keys, country restrictions or prices to bundles, use the instructions.

Create and update promotions

Coupons

To update the promotion:

1. Get data from the catalog with Get coupon promotion or Get list of coupon promotions API methods.
2. Pass new parameter values with the Update coupon promotion API method.
3. Activate the promotion with the Activate coupon promotion API method.

To create a promotion, use the Create coupon promotion API methods, and then Create coupon code to create custom coupons codes or Generate coupon codes to generate random coupon codes.
To deactivate a promotion, use the Deactivate coupon promotion API method.

Promo codes

To update the promotion:

1. Get data from the catalog with Get promo codes promotion or Get list of promo codes promotions API methods.
2. Pass new parameter values with the Update promo codes promotion API method.
3. Activate the promotion with the Activate promo code promotion API method.

To create a promotion, use the Create promo code promotion API methods, and then Create code for promo code promotion to create custom promo codes or Generate codes for promo code promotion to generate random promo codes.
To deactivate a promotion, use the Deactivate promo code promotion API method.

Discounts

To update the promotion:

1. Get data from the catalog with Get item promotion or Get list of item promotions API methods.
2. Pass new parameter values with the Update item promotion API method.
3. Activate the promotion with the Activate promotion API method.

To create a promotion, use the Create discount promotion for item API method.
To deactivate a promotion, use the Deactivate promotion API method.

Bonuses

To update the promotion:

1. Get data from the catalog with Get bonus promotion or Get list of bonus promotions API methods.
2. Pass new parameter values with the Update bonus promotion API method.
3. Activate the promotion with the Activate promotion API method.

To create a promotion, use the Create bonus promotion API method.
To deactivate a promotion, use the Deactivate promotion API method.

Automatic creation of items via API

If you need to create numerous items based on data from your system, you can automate this process using the API.

You need to:

• Export the item data from your system.
• Transform the exported data into a format that matches the data format in the API method of the required item type.
• Create a script that calls the required API method for each item in the export:
  • Create virtual item
  • Create virtual currency
  • Create virtual currency package
  • Create bundle

If you want to use item groups, create them in advance via the Publisher Account interface.

If you want to use multiple types of items, they should be created in the following order:

1. Item groups in the Publisher Account.
2. Virtual currencies.
3. Virtual items.
4. Virtual currency packages.
5. Bundles.

Next is an example of a script that repeatedly calls the Create virtual item method to create virtual items.

The script is developed using JavaScript and the JavaScript runtime — Node.js.

1. Import the fetch function of the “node-fetch” module to send HTTP requests to the Xsolla server.

import fetch from "node-fetch";

2. Set the constants needed for request authorization. Instead of <your project_id from PA> and <your api key from PA>, insert your values for the project ID and API key, which will be encoded using Base64 for subsequent use in API requests.

const projectId = <your project_id from PA>;

const apiKey = <your api key from PA>;

const buff = new Buffer(`${projectId}:${apiKey}`);

const basicAuth = buff.toString('base64')

3. Implement the helper function sleep, which is used to create a delay when sending requests. This is necessary in order not to exceed API request rate limits.

function sleep(ms) {

   return new Promise(resolve => setTimeout(resolve, ms));

}

4. Implement the getItems function, which is specific to your system, to retrieve item data from your system.

async function getItems() {

   // receive items from the original system or read from a pre-prepared file

   return items;

}

5. Implement the prepareData function, which is specific to your system, to format item data in accordance with the data format in the Create virtual item API call.

function prepareData(items) {

   // format items in accordance with API requirements

   return formattedItems;

}

6. Add the createItem function, which sends a POST request to the Xsolla API to create a virtual item.

async function createItem(item) {

   const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items`;



   return await fetch(url, {

       method: "POST",

       headers: {

           Authorization: "Basic " + basicAuth,

           "Content-Type": "application/json"

       },

       body: JSON.stringify(item),

   });

}

7. Add the checkItemExist function, which checks whether a virtual item with a specified SKU exists. The function sends a GET request to the Xsolla API:
   • If a response with a 404 HTTP code is received, the item with the specified SKU is not found, and it needs to be created.
   • If a response with a 200 HTTP code is received, the item with the specified SKU is found and does not need to be created.

async function checkItemExist(sku) {

   const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items/sku/${sku}`;

   const response = await fetch(url, {

       method: "GET",

       headers: {

           Authorization: "Basic " + basicAuth

       }

   });

   return response.status !== 404;

}

8. Add the createItems function, which goes through the list of items and checks whether there is an item with a SKU from your system on the Xsolla side. If there is no item with such a SKU, the function creates it. The progress information is displayed in the console.

async function createItems(items) {

   let success = 0;

   let alreadyCreated = 0;

   for (let i = 0; i < items.length; i++) {

       const item = items[i];

       if (item['sku'] === undefined) {

           console.log(`${i} Field "sku" not specified`);

           continue;

       }

       const sku = item['sku'];

       if (await checkItemExist(sku)) {

           console.log(`${i} Item with sku "${sku}" already created`);

           alreadyCreated++;

           continue;

       }

       const response = await createItem(item);

       if (response.status === 201) {

           console.log(`${i} Item with sku "${sku}" successfully created`)

           success++;

       } else {

           const jsonData = await response.json();

           console.log(`${i} An error occurred while creating the items with sku "${sku}"`);

           console.log(jsonData);

       }

       // add a delay so as not to run into rate limits

       await sleep(500);

   }

   console.log(`${success} items out of ${items.length} created. ${alreadyCreated} items already existed`);

}

9. Add the run function that calls all the above functions in the correct order.

async function run() {

 const items = await getItems();

 const formattedItems = prepareData(items);

 await createItems(formattedItems);

}

The full code:

import fetch from "node-fetch";

const projectId = <your project_id from PA>;
const apiKey = <your api key from PA>;
const buff = new Buffer(`${projectId}:${apiKey}`);
const basicAuth = buff.toString('base64')

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function getItems() {
    // receive items from the original system or read from a pre-prepared file
    return items;
}

function prepareData(items) {
    // format items in accordance with API requirements
    return formatedItems;
}

async function createItem(item) {
    const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items`;

    return await fetch(url, {
        method: "POST",
        headers: {
            Authorization: "Basic " + basicAuth,
            "Content-Type": "application/json"
        },
        body: JSON.stringify(item),
    });
}

async function isItemExisted(sku) {
    const url = `https://store.xsolla.com/api/v2/project/${projectId}/admin/items/virtual_items/sku/${sku}`;
    const response = await fetch(url, {
        method: "GET",
        headers: {
            Authorization: "Basic " + basicAuth
        }
    });
    return response.status !== 404;
}

async function createItems(items) {
    let success = 0;
    let alreadyCreated = 0;
    for (let i = 0; i < items.length; i++) {
        const item = items[i];
        if (item['sku'] === undefined) {
            console.log(`${i} Field "sku" not specified`);
            continue;
        }
        const sku = item['sku'];
        if (await isItemExisted(sku)) {
            console.log(`${i} Item with sku "${sku}" already created`);
            alreadyCreated++;
            continue;
        }
        const response = await createItem(item);
        if (response.status === 201) {
            console.log(`${i} Item with sku "${sku}" successfully created`)
            success++;
        } else {
            const jsonData = await response.json();
            console.log(`${i} An error occurred while creating the items with sku "${sku}"`);
            console.log(jsonData);
        }
        // add a delay so as not to run into rate limits
        await sleep(500);
    }
    console.log(`${success} items out of ${items.length} created. ${alreadyCreated} items already existed`);
}

async function run() {
  const items = await getItems();
  const formattedItems = prepareData(items);
  await createItems(formattedItems);
}

run(); 

Updating by importing from external systems