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

# Build your item catalog

> Creating catalog items, and how stock tracking actually behaves

Items are your reusable catalog: services and goods you bill against by `item_id` instead of retyping a description on every invoice line. This guide covers creating items and the one behavior worth understanding closely: `track_inventory`.

## Create an item

```bash theme={null}
curl -X POST https://app.billbooks.com/api/public-api/v1/items \
  -H "Authorization: Bearer bb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Design consulting, hourly",
    "type": "service",
    "rate": 150,
    "unit": "hour",
    "track_inventory": false
  }'
```

For a physical good with stock on hand:

```bash theme={null}
curl -X POST https://app.billbooks.com/api/public-api/v1/items \
  -H "Authorization: Bearer bb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Branded notebook",
    "type": "goods",
    "rate": 12.5,
    "unit": "unit",
    "track_inventory": true,
    "stock": 200
  }'
```

<Note>
  `stock` is create-only. Once the item exists, `stock` is silently ignored on any `PUT` update, you can't correct a stock count by editing the item directly. Stock only moves through invoicing (see below) or through the internal app.
</Note>

A couple of other fields worth knowing: `hsn` isn't validated at all by the internal app's own entry screen, but the API does validate it since the underlying column is a 20-character varchar, so a value that would silently truncate in the app can get rejected here. `tax_ids` is a full replace on update, whatever list you submit becomes the item's complete tax set, and every id in it has to belong to your organization.

## How stock tracking actually works

Turning `track_inventory` on doesn't just display a number, it wires the item into Billbooks' stock ledger. When an invoice line references this item's `item_id`:

* Stock is deducted by the line's `qty`.
* A ledger row is written recording the sale.

This only happens through the Invoices endpoint, not through Items itself, there's no direct "adjust stock" call on this API. If you delete the invoice later (and deletion is allowed, see [Create and send an invoice](/guides/create-and-send-an-invoice)), the stock deduction is reversed as part of that.

If `track_inventory` is off, `stock` is just a number you set once at creation and nothing automatically changes it.

## List and filter items

```bash theme={null}
curl "https://app.billbooks.com/api/public-api/v1/items?filter[status]=services&filter[q]=design" \
  -H "Authorization: Bearer bb_live_your_key_here"
```

`filter[status]` here is lowercased before use and accepts pseudo-filters like `services`, `goods`, `inventory`, or `non-inventory`, passed straight through to the underlying item model rather than independently validated.

## Update or delete an item

`PUT` follows the same partial-patch rules as Clients, only submitted fields change (remembering that `stock` is the one exception that's silently ignored). `status` is update-only: truthy is active, falsy is inactive.

```bash theme={null}
curl -X DELETE "https://app.billbooks.com/api/public-api/v1/items?id=118" \
  -H "Authorization: Bearer bb_live_your_key_here"
```

Deletion is blocked with `409 Conflict` if the item has ever appeared on a recorded estimate or invoice line. An item that's never been billed deletes outright, with no undo.

## What's next

* [Create and send an invoice](/guides/create-and-send-an-invoice) to see `item_id` and stock deduction in action
* [Create and manage estimates](/guides/create-and-manage-estimates), which reference the same catalog