{
  "openapi": "3.0.3",
  "info": {
    "version": "1.0.0",
    "title": "Backpack API & Webhooks",
    "description": "# Overview\n\nWelcome to the Backpack API, an essential tool to enhance your item-selling strategy and promotional campaigns.\n\nWith Backpack, users can store information about the items they purchased or received for free. When receiving items, users don’t need to use their game ID or go to the game from the distributor site — they can keep items in the Backpack and redeem them later.\n\nAll items purchased or received for free on the distributor website are available to the user in the Metaframe widget or [Xsolla Wallet](https://account.xsolla.com/backpack).\n\nUser flow:\n\n1. The user visits the distribution site.\n2. The user logs in through the Xsolla account in the Metaframe widget.\n3. The user purchases the item or gets it for free and selects the option to move the item to the Backpack.\n4. Information about the received item is transferred to the Backpack.\n5. In the Metaframe widget or Xsolla Wallet, the user opens the **Backpack** section and selects the item.\n6. The user receives the item.\n7. Information about the received item is transferred to the game.\n\n## Features\n\n- **Item Storage:** Users can store information about items purchased or received for free.\n- **Redemption Flexibility:** Items stored in the Backpack can be redeemed at the user's convenience.\n\n## Getting Started\n\nTo get started with Backpack, check out our detailed guide on [Setting up Backpack](/doc/metaframe). This guide will walk you through the process of configuring Backpack to suit your needs.\n\n## Key Entities\n\nBackpack revolves around three major entities:\n\n1. **Items:** The core entities that can be distributed to users.\n2. **Game:** The entity designed to combine items.\n3. **Backpack:** The entity designed to to grant user items in the game.\n\n# Authorization\n\nTo interact with the Backpack API, you need to set up authorization.\n\nFor authorization, you have to provide 2 kinds of headers:\n1. X-HOST-ID header.\n2. Authorization header.\n\n## X-HOST-ID header\n\nIt is a unique header issued by Xsolla.\nTo obtain it, please contact the integration team at integration@xsolla.com or your Customer Success Manager at csm@xsolla.com.\nProvide them with the project ID and merchant ID.\n\nYou can find the merchant ID parameter in your Publisher Account:\n- in the **Project settings > Webhooks** section.\n- in the **Company settings > Company** section.\n- 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>`.\n\nYou can find the project ID parameter in your Publisher Account next to the name of the project.\n\n<div class=\"note\"><b>Note</b><br><br>Keep X-HOST-ID confidential, as it is part of the authentication key.</div>\n\n## Authorization header\n\nSet up user authentication via Xsolla account on Xsolla Wallet by following this [guide](/doc/metaframe/integration-guide/set-up-xsolla-account-login/). This process involves actions in the Publisher Account and assistance from our integration team.\n\nOnce the Xsolla account client is set up, use [this endpoint](/api/login/operation/generate-jwt/) to generate a token. The token is valid for 1 hour, after which you'll need to invoke the endpoint again for a new token.\n\nUse the obtained token by providing the Authorization header with the Bearer token string.\n\n# Webhooks\n\nWebhook notifications associated with the Backpack are listed under the Webhooks tag. For more in-depth information about working with webhooks, refer to our [main webhook documentation](https://developers.xsolla.com/webhooks/overview/#section/Overview).\n\nTo set up webhooks:\n\n1. Open your project in the [Publisher Account](https://publisher.xsolla.com/).\n2. Click **Project settings** in the side menu and navigate to **Webhooks**.\n3. Specify the URL where you want to receive webhooks in the `https://example.com` format.\n4. A secret key to sign project webhooks is generated by default. To generate a new secret key, click the refresh icon.\n5. Click **Enable webhooks**.\n\nIf you have set up a [Metaframe webhook](/doc/metaframe/wallet/metaframe-webhooks/), please contact the integration team at [integration@xsolla.com](mailto:integration@xsolla.com) or your Customer Success Manager at [csm@xsolla.com](mailto:csm@xsolla.com). They will assist you in setting up a second webhook for the project.\n"
  },
  "servers": [
    {
      "url": "https://metaframe.xsolla.com"
    }
  ],
  "tags": [
    {
      "name": "Game",
      "description": "Operations related to creating and updating game entities. Game entities are used to combine and sort items."
    },
    {
      "name": "Items",
      "description": "Operations for creating, managing, and distributing items to users via Backpack. Items are the core entities associated with games."
    },
    {
      "name": "Webhooks",
      "description": "Various events and notifications related to Backpack functionality, such as player validations and item redemptions."
    },
    {
      "name": "User",
      "x-displayName": "Backpack",
      "description": "Endpoints for granting users items from their Backpack, including game keys, virtual items, and virtual currency."
    }
  ],
  "paths": {
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/game_keys": {
      "post": {
        "summary": "Create game keys",
        "description": "Creates a list of game keys and adds them to Backpack of the specified user.",
        "operationId": "create-game-keys",
        "tags": [
          "Items"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/userId"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "requestBody": {
          "description": "A JSON object containing game keys information.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SaveGameKeys"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Game keys were successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GameKeys"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/promo_codes": {
      "post": {
        "summary": "Create promo codes",
        "description": "Creates a list of promo codes with items and adds them to Backpack of the specified user. To get items created using this method, the user copies the promo code from Backpack and enters it on the gaming platform or in the game.",
        "operationId": "create-promo-codes",
        "tags": [
          "Items"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/userId"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "requestBody": {
          "description": "A JSON object containing promo codes information.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavePromoCodes"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Promo codes were successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromoCodesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/virtual_currency": {
      "post": {
        "summary": "Create virtual currency",
        "description": "Creates a list of virtual currency packages and adds them to Backpack of the specified user.",
        "operationId": "create-virtual-currency",
        "tags": [
          "Items"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/userId"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "requestBody": {
          "description": "A JSON object containing virtual currency packages information.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VirtualCurrencies"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Virtual currencies were successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualCurrenciesResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/user/{userId}/virtual_items": {
      "post": {
        "summary": "Create virtual items",
        "description": "Creates a list of virtual items and adds them to Backpack of the specified user.",
        "operationId": "create-virtual-items",
        "tags": [
          "Items"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/userId"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "requestBody": {
          "description": "A JSON object containing virtual items information.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VirtualItems"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Virtual items were successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualItemsResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/users/{userId}/items": {
      "get": {
        "summary": "Get user's Backpack items",
        "description": "Returns the list of items from Backpack of a specified user. Items can be game keys, virtual items, and virtual currency.",
        "operationId": "user-backpack-items-list",
        "tags": [
          "Items"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          },
          {
            "$ref": "#/components/parameters/userId"
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of the element from which the list is generated (the count starts from 0).",
            "schema": {
              "type": "integer",
              "format": "uint32"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Limit for the number of elements on the page. If not specified, all items are returned (default).",
            "schema": {
              "type": "integer",
              "format": "uint32"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The list of items from users's Backpack was succesfully recieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Items"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/users/{userId}/items/{itemId}": {
      "delete": {
        "summary": "Delete item from Backpack",
        "description": "Deletes the specified item from Backpack of the specified user.",
        "operationId": "delete-item",
        "tags": [
          "Items"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          },
          {
            "$ref": "#/components/parameters/userId"
          },
          {
            "$ref": "#/components/parameters/itemId"
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          },
          "400": {
            "description": "Bad request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/merchants/{merchantId}/projects/{projectId}/games": {
      "post": {
        "summary": "Create game",
        "description": "Creates a game entity for a specified project.",
        "operationId": "create-game",
        "tags": [
          "Game"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "requestBody": {
          "description": "A JSON object containing game information.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Game"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Game entity was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GameResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Get games",
        "description": "Retrieves external IDs and names of the created game entities.",
        "operationId": "get-games",
        "tags": [
          "Game"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "responses": {
          "200": {
            "description": "The list of created games was successfully recieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExternalGameIds"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update game",
        "description": "Updates game entity details",
        "operationId": "update-game-details",
        "tags": [
          "Game"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/xHostID"
          },
          {
            "$ref": "#/components/parameters/merchantId"
          },
          {
            "$ref": "#/components/parameters/projectId"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "A JSON object containing game information.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ModifyGameDetails"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No content."
          },
          "401": {
            "description": "Unauthorized.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable entity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/items": {
      "get": {
        "summary": "Get user's Backpack items",
        "description": "Returns the list of items from user's Backpack. Items can be game keys, virtual items, and virtual currency.",
        "operationId": "get-user-backpack-items",
        "tags": [
          "User"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/offset"
          },
          {
            "$ref": "#/components/parameters/limit"
          },
          {
            "name": "group",
            "in": "query",
            "description": "Field by which items should be grouped.",
            "schema": {
              "type": "string"
            },
            "example": "game_name"
          },
          {
            "name": "item_type",
            "in": "query",
            "description": "Type of the item.",
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "game_key",
                  "virtual_item",
                  "virtual_currency",
                  "promo_code"
                ]
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The list of items from users's Backpack was succesfully recieved.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Items"
                    },
                    {
                      "$ref": "#/components/schemas/ItemGroups"
                    }
                  ]
                },
                "examples": {
                  "itemsExample": {
                    "$ref": "#/components/examples/ItemsExample"
                  },
                  "itemGroupsExample": {
                    "$ref": "#/components/examples/ItemGroupsExample"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/items/{itemId}": {
      "get": {
        "summary": "Get user's Backpack item",
        "description": "Returns a specified item from the user's Backpack. The item can be a game key,  a virtual item and a virtual currency.",
        "operationId": "get-user-backpack-item",
        "tags": [
          "User"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/itemId"
          }
        ],
        "responses": {
          "200": {
            "description": "The details of a specified item from user's Backpack was seccessfully recieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The specified item isn't found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/virtual_currency/move_to_game": {
      "post": {
        "summary": "Move user's virtual currency to game",
        "description": "Grants the user virtual currency from Backpack in the game.",
        "operationId": "move-user-virtual-currency-to-game",
        "tags": [
          "User"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MoveVirtualCurrencyToGameRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The user was successfully granted virtual currency in the game."
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/virtual_currency/receive": {
      "post": {
        "summary": "Moves user's virtual currency to Xsolla Wallet",
        "description": "Grants the user virtual currency from Backpack in Xsolla Wallet.",
        "operationId": "move-user-virtual-currency-to-wallet",
        "tags": [
          "User"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReceiveVirtualCurrencyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The user was successfully granted virtual currency in Xsolla Wallet."
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/web/backpack/virtual_items/move_to_game": {
      "post": {
        "summary": "Move user's virtual item to game",
        "description": "Grants the user virtual item from Backpack in the game.",
        "operationId": "move-user-virtual-item-to-game",
        "tags": [
          "User"
        ],
        "servers": [
          {
            "url": "https://metaframe.xsolla.com"
          }
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MoveVirtualItemToGameRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The user was successfully granted virtual item in the game."
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-webhooks": {
    "user-validation": {
      "post": {
        "summary": "Player ID validation",
        "deprecated": true,
        "description": "<div class=\"notice\">This webhook is deprecated. Xsolla sends the <a href=\"/webhooks/operation/user-validation/\">User validation</a> webhook instead.</div> Xsolla sends a webhook with the `user_validation` type to the webhook URL to verify that a player is registered in the game. The request is sent before moving virtual items or currency to the game process.",
        "tags": [
          "Webhooks"
        ],
        "operationId": "user-validation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "notification_type",
                  "settings",
                  "user"
                ],
                "properties": {
                  "notification_type": {
                    "type": "string",
                    "description": "Type of notification."
                  },
                  "settings": {
                    "type": "object",
                    "description": "Custom project settings.",
                    "required": [
                      "merchant_id",
                      "project_id"
                    ],
                    "properties": {
                      "merchant_id": {
                        "type": "integer",
                        "description": "Merchant ID. You can find this parameter in your Publisher Account:\n  - in the **Company settings > Company** section.\n  - 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>`."
                      },
                      "project_id": {
                        "type": "integer",
                        "description": "Project ID. You can find this parameter in your Publisher Account next to the name of the project."
                      }
                    }
                  },
                  "user": {
                    "type": "object",
                    "description": "User information.",
                    "required": [
                      "id"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Player ID in the game."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return an empty body to indicate the player is found.",
            "content": {
              "application/json": {
                "example": null
              }
            }
          },
          "404": {
            "description": "Return in case the player is not found.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "x-examples": {
              "application/json": {
                "INVALID_USER": {
                  "summary": "Invalid user",
                  "value": {
                    "error": {
                      "code": "INVALID_USER",
                      "message": "Invalid user"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Return to indicate temporary errors with your servers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "x-examples": {
              "application/json": {
                "INTERNAL_SERVER_ERROR": {
                  "summary": "Internal Server Error",
                  "value": {
                    "error": {
                      "code": "INTERNAL_SERVER_ERROR",
                      "message": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "CURL",
            "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'Accept: application/json' \\\n-H 'Content-Type: application/json' \\\n-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n    \"notification_type\": \"user_validation\",\n    \"settings\": {\n      \"merchant_id\": 111111,\n      \"project_id\": 222222\n    },\n    \"user\": {\n      \"id\": \"test_player_id\"\n    }\n}'\n"
          }
        ]
      }
    },
    "move-item-to-game": {
      "post": {
        "summary": "Move item to game",
        "deprecated": true,
        "description": "<div class=\"notice\">This webhook is deprecated. Xsolla sends the <a href=\"/webhooks/operation/successful-order-payment/\">Successful payment for order</a> webhook instead.</div> Xsolla sends a webhook with the `move_to_game` type to the webhook URL to deliver the item to player in the game.",
        "tags": [
          "Webhooks"
        ],
        "operationId": "move-item-to-game",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "notification_type",
                  "settings",
                  "items",
                  "user"
                ],
                "properties": {
                  "notification_type": {
                    "type": "string",
                    "description": "Type of notification."
                  },
                  "settings": {
                    "type": "object",
                    "description": "Custom project settings.",
                    "required": [
                      "merchant_id",
                      "project_id"
                    ],
                    "properties": {
                      "merchant_id": {
                        "type": "integer",
                        "description": "Merchant ID. You can find this parameter in your Publisher Account:\n  - in the **Company settings > Company** section.\n  - 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>`."
                      },
                      "project_id": {
                        "type": "integer",
                        "description": "Project ID. You can find this parameter in your Publisher Account next to the name of the project."
                      }
                    }
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "sku",
                        "type"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The unique identifier for the item. Specified when creating item via [API call](/api/backpack/tag/Items/)."
                        },
                        "sku": {
                          "type": "string",
                          "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
                        },
                        "type": {
                          "type": "string",
                          "description": "The item type indicates the category of claimed item.",
                          "x-go-type": "types.ItemType",
                          "enum": [
                            "virtual_item",
                            "virtual_currency"
                          ]
                        },
                        "quantity": {
                          "type": "integer",
                          "format": "uint32",
                          "description": "Item quantity. Applies only to items with the `virtual_currency` type."
                        }
                      }
                    }
                  },
                  "user": {
                    "type": "object",
                    "description": "User information.",
                    "required": [
                      "id"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Player ID in the game."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Return an empty body to indicate the player is found.",
            "content": {
              "application/json": {
                "example": null
              }
            }
          },
          "500": {
            "description": "Return to indicate temporary errors with your servers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            },
            "x-examples": {
              "application/json": {
                "INTERNAL_SERVER_ERROR": {
                  "summary": "Internal Server Error",
                  "value": {
                    "error": {
                      "code": "INTERNAL_SERVER_ERROR",
                      "message": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "label": "CURL",
            "source": "curl -v 'https://your.hostname/your/uri' \\\n-X POST \\\n-H 'Accept: application/json' \\\n-H 'Content-Type: application/json' \\\n-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \\\n-d '{\n    \"notification_type\": \"move_to_game\",\n    \"settings\": {\n      \"merchant_id\": 111111,\n      \"project_id\": 222222\n    },\n    items\": [\n      {\n        \"id\": \"0559dd09-76d5-4c87-8218-2951196467fd\",\n        \"sku\": \"virtual-currency-item_test\",\n        \"type\": \"virtual_currency\",\n        \"quantity\": 10\n      },\n    ]\n    \"user\": {\n      \"id\": \"test_player_id\"\n    }\n}'\n"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "For details check the Authorization section in the left menu."
      }
    },
    "parameters": {
      "xHostID": {
        "in": "header",
        "name": "X-HOST-ID",
        "required": true,
        "description": "A unique header issued by Xsolla. To obtain it, please contact the integration team at integration@xsolla.com or your Customer Success Manager at csm@xsolla.com. Provide them with the project ID and merchant ID. Keep X-HOST-ID confidential, as it is part of the authentication key.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "userId": {
        "in": "path",
        "name": "userId",
        "description": "User ID.",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "merchantId": {
        "in": "path",
        "name": "merchantId",
        "description": "Merchant ID. You can find this parameter in your Publisher Account:\n  - in the **Company settings > Company** section.\n  - 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>`.",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "uint32"
        }
      },
      "projectId": {
        "in": "path",
        "name": "projectId",
        "description": "Project ID. You can find this parameter in your Publisher Account next to the name of the project.",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "uint32"
        }
      },
      "itemId": {
        "in": "path",
        "name": "itemId",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "The unique identifier for the item. Specified when creating item via [API call](/api/backpack/tag/Items/)."
      },
      "offset": {
        "in": "query",
        "name": "offset",
        "description": "Number of the element from which the list is generated (the count starts from 0).",
        "schema": {
          "type": "integer",
          "format": "uint32",
          "default": 0
        }
      },
      "limit": {
        "in": "query",
        "name": "limit",
        "description": "Limit for the number of elements on the page.",
        "schema": {
          "type": "integer",
          "format": "uint32",
          "default": 50
        }
      }
    },
    "schemas": {
      "ItemGroups": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/ItemGroup"
        }
      },
      "ItemGroup": {
        "type": "object",
        "required": [
          "game_name",
          "items"
        ],
        "properties": {
          "game_name": {
            "type": "string"
          },
          "items": {
            "$ref": "#/components/schemas/Items"
          }
        }
      },
      "Items": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/Item"
        }
      },
      "Item": {
        "type": "object",
        "required": [
          "item_id",
          "image_url",
          "image_proxy_url",
          "item_sku",
          "project_id",
          "merchant_id",
          "item_type",
          "price",
          "currency",
          "promo_code",
          "item_name",
          "game_name",
          "external_game_id",
          "code",
          "created_at",
          "item_status",
          "quantity",
          "is_external_vc",
          "platform"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "description": "The unique identifier for the item. Specified when creating item via [API call](/api/backpack/tag/Items/)."
          },
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "item_name": {
            "type": "string",
            "description": "The item's name from the Publisher Account. Currently, only English names are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "image_proxy_url": {
            "type": "string",
            "nullable": true,
            "description": "The URL pointing to the image of the item in the proxy storage, which is displayed to the player in the Metaframe widget. This URL allows you to resize the image by passing the dimensions to the URL as parameters."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "project_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account project ID associated with the item."
          },
          "merchant_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account ID associated with the item."
          },
          "item_type": {
            "type": "string",
            "description": "The item type indicates the category of claimed item.",
            "x-go-type": "types.ItemType",
            "enum": [
              "game_key",
              "promo_code",
              "virtual_item",
              "virtual_currency"
            ]
          },
          "price": {
            "type": "number",
            "description": "The price of the virtual currency item in the specified currency (`currency` parameter). This value represents the cost of acquiring the specified amount of virtual currency. For example, if the price is 10.99 and the currency is USD, it means the cost to obtain the associated amount of virtual currency is $10.99."
          },
          "currency": {
            "type": "string",
            "default": "USD",
            "description": "The currency which prices are displayed in (`USD` by default). Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)."
          },
          "promo_code": {
            "type": "string",
            "description": "Unique case sensitive code that user can redeem in the game to recieve the item. Contains letters and numbers."
          },
          "code": {
            "type": "string",
            "description": "The game key associated with the item."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          },
          "created_at": {
            "type": "string",
            "description": "The timestamp indicates the moment in which the item is claimed by user."
          },
          "item_status": {
            "type": "string",
            "description": "The item status shows stage of item. In this case, the item status will be claimed."
          },
          "quantity": {
            "type": "integer",
            "format": "uint32",
            "description": "Item quantity."
          },
          "is_external_vc": {
            "type": "boolean",
            "description": "Whether the virtual currency is partners' currency or Xsolla currency."
          },
          "platform": {
            "$ref": "#/components/schemas/Platform"
          }
        }
      },
      "MoveVirtualCurrencyToGameRequest": {
        "type": "object",
        "required": [
          "item_id",
          "user_game_id"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "description": "The unique identifier for the item. Specified when creating item via [API call](/api/backpack/tag/Items/)."
          },
          "user_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned to the game. Refer to endpoints under the **Game** tag for additional details."
          }
        }
      },
      "ReceiveVirtualCurrencyRequest": {
        "type": "object",
        "required": [
          "item_id"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "description": "The unique identifier for the item. Specified when creating item via [API call](/api/backpack/tag/Items/)."
          }
        }
      },
      "MoveVirtualItemToGameRequest": {
        "type": "object",
        "required": [
          "item_id",
          "user_game_id"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "description": "The unique identifier for the item. Specified when creating item via [API call](/api/backpack/tag/Items/)."
          },
          "user_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned to the game. Refer to endpoints under the **Game** tag for additional details."
          }
        }
      },
      "ModifyGameDetails": {
        "type": "object",
        "required": [
          "external_game_id"
        ],
        "properties": {
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Used in other requests to associate items, keys, and currencies with a game. Enables grouping items, keys, and currencies under one game in the Metaframe widget."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game."
          },
          "game_image_url": {
            "type": "string",
            "description": "The URL pointing to the image representing the game. It's recommended to upload images that weigh no more than 1 MB. This image is displayed to players in the Metaframe widget."
          }
        }
      },
      "SaveGameKeyItem": {
        "type": "object",
        "required": [
          "image_url",
          "item_sku",
          "code"
        ],
        "properties": {
          "description": {
            "type": "string",
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "code": {
            "type": "string",
            "description": "The game key associated with the item."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "game_image_url": {
            "type": "string",
            "description": "The URL pointing to the image representing the associated game. Refer to endpoints under the **Game** tag for additional details."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          }
        }
      },
      "PromoCode": {
        "type": "object",
        "required": [
          "image_url",
          "item_sku",
          "item_name",
          "promo_code"
        ],
        "properties": {
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "item_name": {
            "type": "string",
            "description": "The item's name from the Publisher Account. Currently, only English names are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "description": {
            "type": "string",
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "promo_code": {
            "type": "string",
            "description": "Unique case sensitive code. Contains letters and numbers."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "game_image_url": {
            "type": "string",
            "description": "The URL pointing to the image representing the associated game."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          }
        }
      },
      "SavePromoCodes": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/PromoCode"
        }
      },
      "SaveGameKeys": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/SaveGameKeyItem"
        }
      },
      "ExternalGameIds": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/ExternalGameId"
        }
      },
      "ExternalGameId": {
        "type": "object",
        "properties": {
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game."
          }
        }
      },
      "VirtualItems": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/VirtualItem"
        }
      },
      "VirtualItem": {
        "type": "object",
        "required": [
          "image_url",
          "item_sku",
          "item_name"
        ],
        "properties": {
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "item_name": {
            "type": "string",
            "description": "The item's name from the Publisher Account. Currently, only English names are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "description": {
            "type": "string",
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "game_image_url": {
            "type": "string",
            "description": "The URL pointing to the image representing the associated game."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          },
          "platform": {
            "$ref": "#/components/schemas/Platform"
          }
        }
      },
      "VirtualCurrencies": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/VirtualCurrency"
        }
      },
      "VirtualCurrency": {
        "type": "object",
        "required": [
          "image_url",
          "item_sku",
          "item_name",
          "price",
          "currency",
          "quantity"
        ],
        "properties": {
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "item_name": {
            "type": "string",
            "description": "The item's name from the Publisher Account. Currently, only English names are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "description": {
            "type": "string",
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "price": {
            "type": "number",
            "description": "The price of the virtual currency item in the specified currency (`currency` parameter). This value represents the cost of acquiring the specified amount of virtual currency. For example, if the price is 10.99 and the currency is USD, it means the cost to obtain the associated amount of virtual currency is $10.99."
          },
          "currency": {
            "type": "string",
            "description": "The currency which prices are displayed in (`USD` by default). Three-letter currency code per [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)."
          },
          "quantity": {
            "type": "integer",
            "format": "uint32",
            "description": "The quantity for the virtual currency package."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "game_image_url": {
            "type": "string",
            "description": "The URL pointing to the image representing the associated game."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game."
          },
          "platform": {
            "$ref": "#/components/schemas/Platform"
          }
        }
      },
      "GameResponse": {
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for the game."
          }
        }
      },
      "Game": {
        "type": "object",
        "required": [
          "merchant_id",
          "project_id"
        ],
        "properties": {
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Used in other requests to associate items, keys, and currencies with a game. Enables grouping items, keys, and currencies under one game in the Metaframe widget."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game."
          },
          "game_image_url": {
            "type": "string",
            "description": "The URL pointing to the image representing the associated game. It's recommended to upload images that weigh no more than 1 MB. This image is displayed to players in the Metaframe widget."
          },
          "merchant_id": {
            "type": "integer",
            "format": "uint32",
            "deprecated": true
          },
          "project_id": {
            "type": "integer",
            "format": "uint32",
            "deprecated": true
          }
        }
      },
      "GameKey": {
        "type": "object",
        "required": [
          "item_id",
          "image_url",
          "item_sku",
          "code",
          "game_name",
          "external_game_id",
          "item_type",
          "created_at",
          "item_status"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for the item."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "code": {
            "type": "string",
            "description": "The game key associated with the item."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          },
          "item_type": {
            "type": "string",
            "x-go-type": "types.ItemType",
            "enum": [
              "game_key"
            ],
            "description": "The item type indicates the category of claimed item. In this case, the item type will be game key."
          },
          "created_at": {
            "type": "string",
            "description": "The timestamp indicates the moment in which the item is claimed by user."
          },
          "item_status": {
            "type": "string",
            "description": "The item status shows stage of item. In this case, the item status will be claimed."
          }
        }
      },
      "GameKeys": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/GameKey"
        }
      },
      "PromoCodeResponse": {
        "type": "object",
        "required": [
          "item_id",
          "image_url",
          "item_sku",
          "project_id",
          "item_name",
          "game_name",
          "external_game_id",
          "merchant_id",
          "item_type",
          "promo_code",
          "item_status",
          "created_at"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for the item."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          },
          "item_type": {
            "type": "string",
            "x-go-type": "types.ItemType",
            "enum": [
              "promo_code"
            ],
            "description": "The item type indicates the category of claimed item. In this case, the item type will be promo code."
          },
          "created_at": {
            "type": "string",
            "description": "The timestamp indicates the moment in which the item is claimed by user."
          },
          "item_status": {
            "type": "string",
            "description": "The item status shows stage of item. In this case, the item status will be claimed."
          },
          "item_name": {
            "type": "string",
            "description": "The item name in the Publisher Account."
          },
          "project_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account project ID associated with the item."
          },
          "merchant_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account ID associated with the item."
          }
        }
      },
      "PromoCodesResponse": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/PromoCodeResponse"
        }
      },
      "VirtualCurrencyResponse": {
        "type": "object",
        "required": [
          "item_id",
          "image_url",
          "item_sku",
          "project_id",
          "item_name",
          "game_name",
          "external_game_id",
          "merchant_id",
          "item_type",
          "price",
          "currency",
          "item_status",
          "quantity",
          "is_external_vc",
          "platform",
          "created_at"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for the item."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          },
          "item_type": {
            "type": "string",
            "x-go-type": "types.ItemType",
            "enum": [
              "virtual_currency"
            ],
            "description": "The item type indicates the category of claimed item. In this case, the item type will be virtual currency."
          },
          "created_at": {
            "type": "string",
            "description": "The timestamp indicates the moment in which the item is claimed by user."
          },
          "item_status": {
            "type": "string",
            "description": "The item status shows stage of item. In this case, the item status will be claimed."
          },
          "item_name": {
            "type": "string",
            "description": "The item name in the Publisher Account."
          },
          "platform": {
            "type": "string",
            "description": "The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.",
            "enum": [
              "steam"
            ]
          },
          "project_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account project ID associated with the item."
          },
          "merchant_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account ID associated with the item."
          },
          "price": {
            "type": "number",
            "description": "The price for the item."
          },
          "currency": {
            "type": "string",
            "description": "The currency for the item price."
          },
          "quantity": {
            "type": "integer",
            "format": "uint32",
            "description": "The quantity for the virtual currency package."
          },
          "is_external_vc": {
            "type": "boolean",
            "description": "An indication to show whether this item is created under Publisher Account."
          }
        }
      },
      "VirtualCurrenciesResponse": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/VirtualCurrencyResponse"
        }
      },
      "VirtualItemsResponse": {
        "type": "array",
        "maxItems": 100,
        "items": {
          "$ref": "#/components/schemas/VirtualItemResponse"
        }
      },
      "VirtualItemResponse": {
        "type": "object",
        "required": [
          "item_id",
          "image_url",
          "item_sku",
          "project_id",
          "game_name",
          "external_game_id",
          "item_name",
          "item_status",
          "merchant_id",
          "item_type",
          "platform",
          "created_at"
        ],
        "properties": {
          "item_id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for the item."
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "The item's description from the Publisher Account. Currently, only English descriptions are supported, and this information is displayed to the user in the Metaframe widget."
          },
          "image_url": {
            "type": "string",
            "description": "The URL pointing to the item's image, which is displayed to the user in the Metaframe widget.\n<div class=\"note\"><b>Note</b><br><br>An image should have an aspect ratio of 8 x 3, meaning that the width to height ratio should be approximately 2.67 (e.g., width = 400 px and height = 150 px). In this case, the image scales with minimal cropping at the edges, so the content remains visible. Optimum minimal resolution is 620 x 233 px (1240 x 466 px for Retina display).</div>"
          },
          "item_sku": {
            "type": "string",
            "description": "The item's Stock Keeping Unit (SKU) from the Publisher Account. The SKU may only contain lowercase Latin alphanumeric characters, periods, dashes, and underscores."
          },
          "game_name": {
            "type": "string",
            "description": "The name of the game associated with the item. Refer to endpoints under the **Game** tag for additional details."
          },
          "external_game_id": {
            "type": "string",
            "description": "The external identifier uniquely assigned by you to represent the game. Refer to endpoints under the **Game** tag for additional details.\n<div class=\"note\"><b>Note</b><br><br>It's recommended to specify it, so that all items associated with the same game would be sorted by the game in the Metaframe widget.</div>"
          },
          "item_type": {
            "type": "string",
            "x-go-type": "types.ItemType",
            "enum": [
              "virtual_currency"
            ],
            "description": "The item type indicates the category of claimed item. In this case, the item type will be virtual currency."
          },
          "created_at": {
            "type": "string",
            "description": "The timestamp indicates the moment in which the item is claimed by user."
          },
          "item_status": {
            "type": "string",
            "description": "The item status shows stage of item. In this case, the item status will be claimed."
          },
          "item_name": {
            "type": "string",
            "description": "The item name in the Publisher Account."
          },
          "platform": {
            "type": "string",
            "description": "The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.",
            "enum": [
              "steam"
            ]
          },
          "project_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account project ID associated with the item."
          },
          "merchant_id": {
            "type": "integer",
            "format": "uint32",
            "description": "The Publisher Account ID associated with the item."
          }
        }
      },
      "Platform": {
        "type": "string",
        "description": "The game platform associated with the item. If specified, the user needs to link their game platform account to Backpack to get the item.",
        "enum": [
          "steam"
        ]
      },
      "Error": {
        "type": "object",
        "required": [
          "message_id",
          "message"
        ],
        "properties": {
          "message_id": {
            "type": "string",
            "x-omitempty": true,
            "nullable": true,
            "description": "A unique identifier that is used for tracking and associating log entries related to this specific request or operation. This ID can be helpful for troubleshooting, debugging, and auditing purposes."
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "examples": {
      "ItemGroupsExample": {
        "summary": "A list of item groups",
        "value": [
          {
            "game_name": "Epic Adventure",
            "items": [
              {
                "item_id": "item123",
                "item_sku": "sku_item_001",
                "item_name": "Magic Sword",
                "image_url": "https://example.com/images/item123.png",
                "image_proxy_url": "https://proxy.example.com/images/item123.png?w=620&h=233",
                "description": "A powerful sword with magical properties.",
                "project_id": 12345,
                "merchant_id": 98765,
                "item_type": "virtual_currency",
                "price": 10.99,
                "currency": "USD",
                "promo_code": "",
                "code": "",
                "game_name": "Epic Adventure",
                "external_game_id": "game_456",
                "created_at": "2023-10-24T14:53:00Z",
                "item_status": "claimed",
                "quantity": 2,
                "is_external_vc": false,
                "platform": "steam"
              }
            ]
          },
          {
            "game_name": "Mystic Quest",
            "items": [
              {
                "item_id": "item789",
                "item_sku": "sku_item_003",
                "item_name": "Shield of Valor",
                "image_url": "https://example.com/images/item789.png",
                "image_proxy_url": "https://proxy.example.com/images/item789.png?w=620&h=233",
                "description": "A legendary shield with the power to block any attack.",
                "project_id": 67890,
                "merchant_id": 54321,
                "item_type": "promo_code",
                "price": null,
                "currency": "USD",
                "promo_code": "PROMO789",
                "code": "",
                "game_name": "Mystic Quest",
                "external_game_id": "game_789",
                "created_at": "2023-10-24T15:00:00Z",
                "item_status": "claimed",
                "quantity": 1,
                "is_external_vc": false,
                "platform": ""
              }
            ]
          }
        ]
      },
      "ItemsExample": {
        "summary": "A list of items",
        "value": [
          {
            "item_id": "item123",
            "item_sku": "sku_item_001",
            "item_name": "Magic Sword Game Key",
            "image_url": "https://example.com/images/item123.png",
            "image_proxy_url": "https://proxy.example.com/images/item123.png?w=620&h=233",
            "description": "A powerful sword with magical properties.",
            "project_id": 12345,
            "merchant_id": 98765,
            "item_type": "game_key",
            "price": null,
            "currency": "USD",
            "promo_code": "",
            "code": "ABC123-DEF456-GHI789",
            "game_name": "Epic Adventure",
            "external_game_id": "game_456",
            "created_at": "2023-10-24T14:53:00Z",
            "item_status": "claimed",
            "quantity": 1,
            "is_external_vc": false,
            "platform": "steam"
          },
          {
            "item_id": "item456",
            "item_sku": "sku_item_002",
            "item_name": "Healing Potion",
            "image_url": "https://example.com/images/item456.png",
            "image_proxy_url": "https://proxy.example.com/images/item456.png?w=620&h=233",
            "description": "Restores 50% of health.",
            "project_id": 12345,
            "merchant_id": 98765,
            "item_type": "virtual_item",
            "price": 5.99,
            "currency": "USD",
            "promo_code": "",
            "code": "",
            "game_name": "Epic Adventure",
            "external_game_id": "game_456",
            "created_at": "2023-10-24T14:55:00Z",
            "item_status": "claimed",
            "quantity": 0,
            "is_external_vc": false,
            "platform": ""
          }
        ]
      }
    }
  }
}