openapi: 3.0.3
info:
  version: 1.0.0
  title: Backpack API & Webhooks
  description: >
    # Overview


    Welcome to the Backpack API, an essential tool to enhance your item-selling
    strategy and promotional campaigns.


    With 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.


    All 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).


    User flow:


    1. The user visits the distribution site.

    2. The user logs in through the Xsolla account in the Metaframe widget.

    3. The user purchases the item or gets it for free and selects the option to
    move the item to the Backpack.

    4. Information about the received item is transferred to the Backpack.

    5. In the Metaframe widget or Xsolla Wallet, the user opens the **Backpack**
    section and selects the item.

    6. The user receives the item.

    7. Information about the received item is transferred to the game.


    ## Features


    - **Item Storage:** Users can store information about items purchased or
    received for free.

    - **Redemption Flexibility:** Items stored in the Backpack can be redeemed
    at the user's convenience.


    ## Getting Started


    To 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.


    ## Key Entities


    Backpack revolves around three major entities:


    1. **Items:** The core entities that can be distributed to users.

    2. **Game:** The entity designed to combine items.

    3. **Backpack:** The entity designed to to grant user items in the game.


    # Authorization


    To interact with the Backpack API, you need to set up authorization.


    For authorization, you have to provide 2 kinds of headers:

    1. X-HOST-ID header.

    2. Authorization header.


    ## X-HOST-ID header


    It is 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.


    You can find the merchant ID parameter in your Publisher Account:

    - in the **Project settings > Webhooks** section.

    - in the **Company settings > Company** section.

    - in the URL in the browser address bar on any Publisher Account page. The
    URL has the following format: `https://publisher.xsolla.com/<merchant
    ID>/<Publisher Account section>`.


    You can find the project ID parameter in your Publisher Account next to the
    name of the project.


    <div class="note"><b>Note</b><br><br>Keep X-HOST-ID confidential, as it is
    part of the authentication key.</div>


    ## Authorization header


    Set 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.


    Once 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.


    Use the obtained token by providing the Authorization header with the Bearer
    token string.


    # Webhooks


    Webhook 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).


    To set up webhooks:


    1. Open your project in the [Publisher
    Account](https://publisher.xsolla.com/).

    2. Click **Project settings** in the side menu and navigate to **Webhooks**.

    3. Specify the URL where you want to receive webhooks in the
    `https://example.com` format.

    4. A secret key to sign project webhooks is generated by default. To
    generate a new secret key, click the refresh icon.

    5. Click **Enable webhooks**.


    If 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.
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:
                          - in the **Company settings > Company** section.
                          - in the URL in the browser address bar on any Publisher Account page. The URL has the following format: `https://publisher.xsolla.com/<merchant ID>/<Publisher Account section>`.
                    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' \

            -X POST \

            -H 'Accept: application/json' \

            -H 'Content-Type: application/json' \

            -H 'Authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                "notification_type": "user_validation",
                "settings": {
                  "merchant_id": 111111,
                  "project_id": 222222
                },
                "user": {
                  "id": "test_player_id"
                }
            }'
  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:
                          - in the **Company settings > Company** section.
                          - in the URL in the browser address bar on any Publisher Account page. The URL has the following format: `https://publisher.xsolla.com/<merchant ID>/<Publisher Account section>`.
                    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' \

            -X POST \

            -H 'Accept: application/json' \

            -H 'Content-Type: application/json' \

            -H 'Authorization: Signature
            13342703ccaca5064ad33ba451d800c5e823db8f' \

            -d '{
                "notification_type": "move_to_game",
                "settings": {
                  "merchant_id": 111111,
                  "project_id": 222222
                },
                items": [
                  {
                    "id": "0559dd09-76d5-4c87-8218-2951196467fd",
                    "sku": "virtual-currency-item_test",
                    "type": "virtual_currency",
                    "quantity": 10
                  },
                ]
                "user": {
                  "id": "test_player_id"
                }
            }'
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:
          - in the **Company settings > Company** section.
          - in the URL in the browser address bar on any Publisher Account page. The URL has the following format: `https://publisher.xsolla.com/<merchant ID>/<Publisher Account section>`.
      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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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.

            <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: ''
