> ## Documentation Index
> Fetch the complete documentation index at: https://developers.teambuilder.ge/llms.txt
> Use this file to discover all available pages before exploring further.

# List shop items

> The rewards your employees can redeem, with your coin prices and stock.

<Tip>
  See the [shop catalogue guide](/guides/shop-catalogue) for how prices and stock behave.
</Tip>


## OpenAPI

````yaml api-reference/openapi.json GET /v1/shop/items
openapi: 3.0.0
info:
  title: TeamBuilder API
  description: >-
    The TeamBuilder API gives your own systems access to your company's
    gamification data (employees, leaderboards, departments and the rewards
    shop) and lets you push your employee roster from your HR system. Send every
    request to `https://api.teambuilder.ge/v1` with your API key as
    `Authorization: Bearer <key>`: live keys (`tb_live_…`) work on your real
    data, test keys (`tb_test_…`) on a sandbox company with sample data.
    Responses are JSON with snake_case fields, cursor-based pagination and
    `X-RateLimit-*` headers. For keys, scopes or help, contact
    [contact@teambuilder.ge](mailto:contact@teambuilder.ge).
  version: '1.0'
  contact:
    name: TeamBuilder support
    url: https://teambuilder.ge
    email: contact@teambuilder.ge
servers:
  - url: https://api.teambuilder.ge
    description: Production
security: []
tags:
  - name: Status
    description: Check that your API key works and see what it can access.
  - name: Employees
    description: >-
      Your active employees, their gamification stats and the badges they hold.
      Requires the `employees:read` scope.
  - name: Leaderboard
    description: >-
      XP rankings of your employees for a chosen period, company-wide or grouped
      by department. Requires the `leaderboard:read` scope.
  - name: Departments
    description: Your company's department tree. Requires the `departments:read` scope.
  - name: Shop
    description: >-
      The rewards your employees can redeem with their coins. Requires the
      `shop:read` scope.
  - name: Roster sync
    description: >-
      Keep TeamBuilder in step with your HR system by pushing your employee
      roster. Requires the `employees:write` scope, which is issued on request.
paths:
  /v1/shop/items:
    get:
      tags:
        - Shop
      summary: List shop items
      description: >-
        Returns the rewards your employees can redeem with their coins, with the
        prices and stock set for your company, oldest first.


        Use it to show your reward catalogue on your intranet, optionally one
        `category` at a time.


        **Notes**


        - Items your company has switched off in the admin portal are not
        listed.
      operationId: listShopItems
      parameters:
        - name: cursor
          required: false
          in: query
          description: >-
            The `pagination.next_cursor` of the previous page. Omit it, or send
            it empty, for the first page. A cursor is opaque and works only on
            the endpoint that returned it, for the same company.
          schema:
            maxLength: 512
            example: djEuQ2hhY2hhMjAuZXhhbXBsZS1jdXJzb3I
            type: string
        - name: limit
          required: false
          in: query
          description: How many items to return per page, from 1 to 100.
          schema:
            minimum: 1
            maximum: 100
            default: 25
            example: 25
            type: integer
        - name: category
          required: false
          in: query
          description: Only items of this category.
          schema:
            example: perk
            type: string
            enum:
              - gift_card
              - merch
              - perk
              - donation
              - experience
      responses:
        '200':
          description: A page of shop items.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopItemList'
        '400':
          description: >-
            A query parameter or the `cursor` is invalid. `message` names the
            problem.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: validation_failed
                  message: limit must not be greater than 100
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '401':
          description: The API key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Invalid API key
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '403':
          description: Your API key does not have the `shop:read` scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: 'This API key lacks the required scope: shop:read'
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '429':
          description: >-
            Your API key made more requests than its limit allows (60 per minute
            unless agreed otherwise), or too many requests came from your IP
            address. Wait `Retry-After` seconds, then retry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests. Retry after 30 seconds.
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
      security:
        - api-key: []
components:
  headers:
    X-Request-Id:
      description: Unique id of this request. Quote it when you contact support.
      schema:
        type: string
        example: req_7Hq2LmX9vT4kPz1RbN8sWc
    X-RateLimit-Limit:
      description: Requests your API key may make per minute.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
        example: 57
    X-RateLimit-Reset:
      description: When the current window ends, as a Unix timestamp in seconds.
      schema:
        type: integer
        example: 1792483260
    WWW-Authenticate:
      description: The authentication scheme to use.
      schema:
        type: string
        example: Bearer realm="TeamBuilder API"
    Retry-After:
      description: Seconds to wait before you retry.
      schema:
        type: integer
        example: 30
  schemas:
    ShopItemList:
      type: object
      properties:
        data:
          description: Items on this page, oldest first.
          type: array
          items:
            $ref: '#/components/schemas/ShopItem'
        pagination:
          description: Where the next page starts.
          allOf:
            - $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    Error:
      type: object
      properties:
        error:
          description: What went wrong, and the id that traces the request.
          allOf:
            - $ref: '#/components/schemas/ErrorDetail'
      description: Every error response has this shape, whatever its status code.
      required:
        - error
    ShopItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: TeamBuilder id of the item.
          example: e7a4c2d9-1f3b-4a6e-8c5d-9b0f2e4a6c81
        name:
          type: string
          description: Display name.
          example: Extra day off
        description:
          type: string
          nullable: true
          description: What the employee gets. Null if the item has no description.
          example: One additional day of paid leave, to use within 12 months.
        category:
          description: |-
            The kind of reward:
            - `gift_card`: a gift card or voucher.
            - `merch`: branded merchandise.
            - `perk`: a workplace perk, such as an extra day off.
            - `donation`: a donation to a cause.
            - `experience`: an activity or event.
          example: perk
          allOf:
            - $ref: '#/components/schemas/ShopItemCategory'
        image_url:
          type: string
          nullable: true
          format: uri
          description: URL of the item image. Null if it has none.
          example: https://files.example.com/shop/extra-day-off.png
        coin_price:
          type: integer
          minimum: 0
          description: Price in coins, as set for your company's shop.
          example: 1500
        stock_remaining:
          type: integer
          nullable: true
          minimum: 0
          description: Units left to redeem. Null means unlimited.
          example: 12
        is_new:
          type: boolean
          description: Whether the shop highlights the item as new.
          example: true
      description: A reward your employees can redeem with coins.
      required:
        - id
        - name
        - description
        - category
        - image_url
        - coin_price
        - stock_remaining
        - is_new
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
          description: Pass it as `cursor` to read the next page. Null on the last page.
          example: djEuQ2hhY2hhMjAuZXhhbXBsZS1jdXJzb3I
      required:
        - next_cursor
    ErrorDetail:
      type: object
      properties:
        code:
          description: >-
            Machine-readable error type. Branch on this, not on `message`:

            - `validation_failed` (400): a parameter, cursor or body field is
            invalid.

            - `unauthorized` (401): the API key is missing, unknown, revoked or
            expired.

            - `forbidden` (403): the key does not have the scope this endpoint
            requires.

            - `not_found` (404): the resource does not exist in your company.

            - `conflict` (409): the request clashes with work in progress, such
            as another roster sync.

            - `length_required` (411): the request body was sent without a
            `Content-Length` header.

            - `payload_too_large` (413): the request body is larger than the
            endpoint accepts.

            - `rate_limit_exceeded` (429): the key made too many requests; wait
            for `Retry-After` seconds.

            - `bad_request` (other 4xx): the request could not be accepted as
            sent.

            - `internal_error` (500): something failed on our side; contact
            support with the `request_id`.
          example: validation_failed
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable explanation for developers. It may change; do not
            parse it.
          example: limit must not be greater than 100
        request_id:
          type: string
          description: >-
            Unique id of the request, also sent as the `X-Request-Id` header.
            Quote it when you contact support.
          example: req_7Hq2LmX9vT4kPz1RbN8sWc
      required:
        - code
        - message
        - request_id
    ShopItemCategory:
      type: string
      enum:
        - gift_card
        - merch
        - perk
        - donation
        - experience
      description: |-
        The kind of reward:
        - `gift_card`: a gift card or voucher.
        - `merch`: branded merchandise.
        - `perk`: a workplace perk, such as an extra day off.
        - `donation`: a donation to a cause.
        - `experience`: an activity or event.
    ErrorCode:
      type: string
      enum:
        - bad_request
        - validation_failed
        - unauthorized
        - forbidden
        - not_found
        - conflict
        - length_required
        - payload_too_large
        - rate_limit_exceeded
        - internal_error
      description: >-
        Machine-readable error type. Branch on this, not on `message`:

        - `validation_failed` (400): a parameter, cursor or body field is
        invalid.

        - `unauthorized` (401): the API key is missing, unknown, revoked or
        expired.

        - `forbidden` (403): the key does not have the scope this endpoint
        requires.

        - `not_found` (404): the resource does not exist in your company.

        - `conflict` (409): the request clashes with work in progress, such as
        another roster sync.

        - `length_required` (411): the request body was sent without a
        `Content-Length` header.

        - `payload_too_large` (413): the request body is larger than the
        endpoint accepts.

        - `rate_limit_exceeded` (429): the key made too many requests; wait for
        `Retry-After` seconds.

        - `bad_request` (other 4xx): the request could not be accepted as sent.

        - `internal_error` (500): something failed on our side; contact support
        with the `request_id`.
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: API key — `tb_live_…` for production data, `tb_test_…` for the sandbox.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.