Build a reusable catalog of rates

Saved items are a per-business rate catalog: a name, a rate, and optional description, unit, type and tax rate. Invoices and estimates accept item_id or an exact item_name and copy the stored description and rate from the catalog.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: Anyone whose agent drafts invoices from a prompt, where "bill 3 hours of Consulting" has to resolve to a real price.
Billr capabilities used: list_itemscreate_itemupdate_itemcreate_invoice

What you need first

The client you bill most often, added with create_client.
The rate, billing unit and short description you want on documents.
A key with the Read and draft profile so the catalog can be written, not just read.

Step by step

01Look before you add
list_items takes a search term and returns every active item with its stored rate. A short catalog that people trust beats a long one with three spellings of the same service.

02Create each item once

rate and name are required. unit and type are labels that print next to the price, and tax_rate is optional per item.

create_item  {
  "name": "Consulting",
  "description": "Senior consulting, billed hourly",
  "rate": 150,
  "unit": "hour",
  "type": "service"
}

03Correct instead of duplicating
update_item accepts item_id or an exact item_name, and can change the rate, description, unit, type or tax rate. Set is_active: false to retire a rate without breaking the documents that already used it.
04Bill from the catalog
In create_invoice and create_estimate, a line can reference item_id or item_name instead of a description and rate. The server copies the stored description and rate, so the prompt can stay short.
Example
```
create_invoice  {
  "request_id": "7c3d5a82-9e14-4b76-8f02-3a6c1d9e4b58",
  "client_id": "9f2a4d18-3b7c-4a6e-8f0d-1c5b2e9a7d44",
  "line_items": [{ "item_name": "Consulting", "quantity": 3 }]
}
```

Worked example

Fictional account, field names as returned by the server

You say

Add Consulting at $150 an hour to my rate list.

Your agent calls

create_item { "name": "Consulting", "description": "Senior consulting, billed hourly", "rate": 150, "unit": "hour", "type": "service" }
list_items { "search": "Consult" }

Expected responses, abridged

{
  "summary": "Saved \"Consulting\" at 150 per hour",
  "item": {
    "id": "c5a9e1d4-7b23-4f68-9a10-3e6d2c8b4f17",
    "name": "Consulting",
    "description": "Senior consulting, billed hourly",
    "type": "service",
    "rate": 150,
    "unit": "hour",
    "is_active": true
  }
}

Limits and gotchas

unit is a label, not a conversion. "day" does not become eight hours; the quantity you pass is what prints.
Item names are unique only by convention. Two items called "Design" make item_name ambiguous, so prefer item_id for anything long-lived.
Retiring an item with is_active: false hides it from list_items unless you pass include_inactive: true; documents that already used it are untouched.
Catalog items price lines. They do not change tax handling on an existing draft, which you set with update_draft_invoice.

Troubleshooting

create_invoice rejects a line with "Could not resolve line items": The item_name did not match exactly. Run list_items with a search term and pass the returned name or the item_id.
update_item changed the wrong item: item_name must match one stored name. Pass item_id instead, which is what list_items returns.
An old invoice shows a rate you no longer charge: Invoices store the rate they were created with. Change the catalog for future documents; correct the draft itself with update_draft_invoice while it is still a draft.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.