How to create and update an item catalog using JSON import

You can create, update, or deactivate items using import from a JSON file.

Note
You can create, update, or deactivate items using API calls or manually in the Publisher Account. However, for each item, you need to perform a separate request or action. With import, you can perform these actions for multiple items simultaneously by specifying them in a single JSON file.

With this tool, you can:

Features:

  • Support for the following types of items:
    • virtual items
    • virtual currency
    • virtual currency packages
    • bundles
  • Data validation. If the file structure or data format does not meet the requirements, you will see a list of errors when importing.

Limitations:

Note
For pre-created items, you can import regional prices from a CSV file.

Import of the item catalog

To import an item catalog from a file:

  1. Open the project in Publisher Account.
  2. In the side menu, click Store and go to the Virtual currency, Virtual items, or Bundles section.
  3. Click Import items.

  1. Choose the action:
    • Add new items — only items with new SKUs will be added.
    • Add new items and update existing ones — items with new SKUs will be added and data of existing items will be updated.
    • Add new, update existing, disable missing items — items with SKUs from the file will be added/updated. If there is an item in the catalog, but there is no such SKU in the file, the status of the item in the Publisher Account will be changed to Partially available — item cannot be purchased separately but is available as part of a bundle or bonus.

  1. Fill in the file for import:
    • Download the file template in the download window and fill it in according to the example below.
    • Export the items and use the exported file as a template.
    • Create your own JSON file and fill it out as per the example below.

An example of a full JSON file:

Copy
Full screen
Small screen

{
    "virtual_currency": [
        {
            "sku": "Gem_test_import",
            "name": {
                "en": "Gem_test_import"
            },
            "type": "virtual_currency",
            "description": {
                "en": "my test imported currency"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/merchant/default-dc-image.png",
            "description": {
                "en": "my test imported currency",
                "de": "meine importierte Testwährung"
            },
            "attributes": [],
            "is_free": false,
            "order": 1,
            "groups": [],
            "regional_prices": [],
            "prices": [
                {
                    "amount": 2,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "media_list": [],
            "vc_prices": [],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "inventory_options": {
                "consumable": true,
                "expiration_period": null
            },
            "is_hard": false
        }
    ],
    "virtual_items": [
        {
            "sku": "event_access_test_import",
            "name": {
                "en": "Special Event Access_test_import"
            },
            "type": "virtual_good",
            "description": {
                "en": "Get special event access as a bonus only on your first purchase. Find the right doggy at the Robo-Dog Exhibition!"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/images/1e3ef1a96cc9dd8d98bc124d5d6fad79.png",
            "long_description": null,
            "attributes": [],
            "is_free": false,
            "order": 1,
            "groups": [
                "my_test_group"
            ],
            "regional_prices": [],
            "prices": [
                {
                    "amount": 35,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "media_list": [],
            "vc_prices": [],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "inventory_options": {
                "consumable": true,
                "expiration_period": null
            }
        }
    ],
    "virtual_currency_packages": [
        {
            "item_id": 441982,
            "sku": "small_gold_pack_test_import",
            "type": "bundle",
            "name": {
                "en": "Small gold pack"
            },
            "bundle_type": "virtual_currency_package",
            "description": {
                "en": "Gold x100"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/images/ba43c46ea75fd5713c210f5736993a92.png",
            "vc_prices": [],
            "regional_prices": [],
            "prices": [
                {
                    "amount": 5,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "attributes": [],
            "long_description": null,
            "media_list": [],
            "order": 100000000,
            "is_free": false,
            "groups": [],
            "content": [
                {
                    "sku": "Gem_test_import",
                    "quantity": 100
                }
            ]
        }
    ],
    "bundles": [
        {
            "item_id": 684024,
            "sku": "start_pack_test_import_test_import",
            "type": "bundle",
            "name": {
                "en": "Legendary Start Pack"
            },
            "bundle_type": "standard",
            "description": {
                "en": "Crystal x 1\nGem x 1"
            },
            "image_url": "https://cdn3.xsolla.com/img/misc/merchant/default-dc-image.png",
            "regional_prices": [],
            "prices": [
                {
                    "amount": 20,
                    "currency": "USD",
                    "is_default": true,
                    "is_enabled": true
                }
            ],
            "virtual_prices": [],
            "is_enabled": true,
            "is_show_in_store": true,
            "regions": [],
            "limits": {
                "per_user": null,
                "per_item": null,
                "recurrent_schedule": null
            },
            "periods": [],
            "attributes": [],
            "long_description": null,
            "media_list": [],
            "order": 5,
            "is_free": false,
            "groups": [
                "my_test_group"
            ],
            "content": [
                {
                    "sku": "Gem_test_import",
                    "quantity": 1
                },
                {
                    "sku": "event_access_test_import",
                    "quantity": 1
                }
            ]
        }
    ]
}

  1. Upload the full file to the corresponding field in the import window.
  2. If there are errors during import, a list of these errors and recommendations for correction will be displayed in the import window. Make the necessary changes to the file and upload it again.

After successful upload, the items with the specified SKUs will be created, updated, or disabled.

Export of the item catalog

To export an item or item catalog to a JSON file:

  1. Open the project in the Publisher Account.
  2. In the side menu, click Store and go to the Virtual currency, Virtual items, or Bundles section.
  3. Click Export items.

  1. Choose the action:
    • Export all items — the entire catalog of all types of items of this project will be exported. For example, if you navigate to the Virtual Currency section and export all items, the JSON file will unload virtual currencies, virtual currency packages, virtual items, game key packages of your project.
    • Export only selected items — in the opened window select the items that should be exported.

  1. Click Export.

The JSON file download will start automatically.

Was this article helpful?
Thank you!
Is there anything we can improve? Message
We’re sorry to hear that
Please explain why this article wasn’t helpful to you. Message
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.
Last updated: May 31, 2024

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!