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
For a physical good with stock on hand:
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.
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), 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
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.
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
