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

# Shop catalogue

> Show the rewards your employees can redeem with their coins, with your company's prices and live stock.

[`GET /v1/shop/items`](/api-reference/shop/list-shop-items) returns your company's reward catalogue as your employees see it in TeamBuilder. It needs the `shop:read` scope.

```bash theme={null}
curl "https://api.teambuilder.ge/v1/shop/items?category=gift_card&limit=20" \
  -H "Authorization: Bearer $TEAMBUILDER_API_KEY"
```

```json Response theme={null}
{
  "data": [
    {
      "id": "7c2e9f14-3b6a-4d85-9e17-1a4c8b2f6d03",
      "name": "Coffee voucher",
      "description": "A coffee on us at any partner café.",
      "category": "gift_card",
      "image_url": null,
      "coin_price": 450,
      "stock_remaining": 12,
      "is_new": true
    }
  ],
  "pagination": { "next_cursor": null }
}
```

## What the catalogue contains

Only items **enabled for your company** are returned. Items your admins have switched off never appear, so you can render the response as is.

`category` is one of `gift_card`, `merch`, `perk`, `donation` or `experience`; pass it as a query parameter to show one category.

## Prices

`coin_price` is the **effective** price for your employees: the price your admins set for your company when they set one, otherwise TeamBuilder's default price for the item. Prices are in coins only; the API exposes no money amounts.

To show whether someone can afford an item, compare `coin_price` with their `coins` from [employee stats](/guides/employee-widgets).

## Stock

| `stock_remaining` | Meaning | Suggested display |
| - | - | - |
| `null` | Unlimited | No stock indicator |
| `0` | Sold out | Keep the item visible, marked as unavailable |
| `1` or more | Units left before the limit your admins set | "12 left" when the number is low |

Stock falls as employees redeem, so treat it as a snapshot. A cache of a few minutes is fine for display; the final check happens when an employee redeems in TeamBuilder.

## Redemption happens in TeamBuilder

The API is read-only for the shop. Employees redeem in their TeamBuilder portal, where approvals, fulfilment and coin holds are handled. Link each item to the portal rather than building a checkout of your own.

<Tip>
  `is_new` is a highlight your admins set on an item; use it to badge the item as new. Cache the catalogue on your server: it changes only when admins edit it or stock moves.
</Tip>


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