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.
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.
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), 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.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Billbooks Developers","colors":{"primary":"#114a4d","light":"#5eead4","dark":"#114a4d"},"logo":{"light":"https://mintcdn.com/billbooks/jXmJmhNHvMwPE891/logo/light.svg?fit=max\u0026auto=format\u0026n=jXmJmhNHvMwPE891\u0026q=85\u0026s=881e2364171dc06515500a6ca77a20ef","dark":"https://mintcdn.com/billbooks/jXmJmhNHvMwPE891/logo/dark.svg?fit=max\u0026auto=format\u0026n=jXmJmhNHvMwPE891\u0026q=85\u0026s=6f532cce98c5bd0e5f7de9d81bb43305"},"favicon":"https://mintcdn.com/billbooks/jXmJmhNHvMwPE891/favicon.png?fit=max\u0026auto=format\u0026n=jXmJmhNHvMwPE891\u0026q=85\u0026s=45d8929f4ce18cdd11cccdb067a90465","navbar":{"links":[{"href":"https://www.billbooks.com","label":"Billbooks.com"}],"primary":{"type":"button","label":"Start free trial","href":"https://app.billbooks.com/sign-up"}},"footer":{"socials":{}},"search":{"prompt":"Search the Billbooks developer docs"},"fonts":{"family":"IBM Plex Sans"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"billbooks","hasAudioNarration":false,"actualSubdomain":"billbooks","customDomains":["docs.billbooks.com"],"gitSource":{"type":"github","owner":"billbooks-pty-ltd","repo":"billbooks-developer-docs","deployBranch":"master","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6a8d23cfac857e7e139f16c6","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Guides","count":10},{"language":"default","tag":"Get Started","count":5},{"language":"default","tag":"How-to guides","count":5},{"language":"default","tag":"API Reference","count":1},{"language":"default","tag":"Overview","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[]}
{"page":{"pagePath":"guides/build-your-item-catalog","slug":"/guides/build-your-item-catalog","pageMetadata":{"title":"Build your item catalog","description":"Creating catalog items, and how stock tracking actually behaves","href":"/guides/build-your-item-catalog"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Creating catalog items, and how stock tracking actually behaves\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Note}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Note)_missingMdxReference(`Note`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Items are your reusable catalog: services and goods you bill against by `,_jsx(_components.code,{children:`item_id`}),` instead of retyping a description on every invoice line. This guide covers creating items and the one behavior worth understanding closely: `,_jsx(_components.code,{children:`track_inventory`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`create-an-item`,children:`Create an item`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`10`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`10`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://app.billbooks.com/api/public-api/v1/items`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer bb_live_your_key_here\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"name\": \"Design consulting, hourly\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"type\": \"service\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"rate\": 150,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"unit\": \"hour\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"track_inventory\": false`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`For a physical good with stock on hand:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`11`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`11`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` POST`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://app.billbooks.com/api/public-api/v1/items`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer bb_live_your_key_here\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` '{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"name\": \"Branded notebook\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"type\": \"goods\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"rate\": 12.5,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"unit\": \"unit\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"track_inventory\": true,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"stock\": 200`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsx(Note,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`stock`}),` is create-only. Once the item exists, `,_jsx(_components.code,{children:`stock`}),` is silently ignored on any `,_jsx(_components.code,{children:`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.`]})}),`\n`,_jsxs(_components.p,{children:[`A couple of other fields worth knowing: `,_jsx(_components.code,{children:`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. `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsx(Heading,{level:`2`,id:`how-stock-tracking-actually-works`,children:`How stock tracking actually works`}),`\n`,_jsxs(_components.p,{children:[`Turning `,_jsx(_components.code,{children:`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 `,_jsx(_components.code,{children:`item_id`}),`:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Stock is deducted by the line’s `,_jsx(_components.code,{children:`qty`}),`.`]}),`\n`,_jsx(_components.li,{children:`A ledger row is written recording the sale.`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`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 `,_jsx(_components.a,{href:`/guides/create-and-send-an-invoice`,children:`Create and send an invoice`}),`), the stock deduction is reversed as part of that.`]}),`\n`,_jsxs(_components.p,{children:[`If `,_jsx(_components.code,{children:`track_inventory`}),` is off, `,_jsx(_components.code,{children:`stock`}),` is just a number you set once at creation and nothing automatically changes it.`]}),`\n`,_jsx(Heading,{level:`2`,id:`list-and-filter-items`,children:`List and filter items`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"https://app.billbooks.com/api/public-api/v1/items?filter[status]=services\u0026filter[q]=design\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer bb_live_your_key_here\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`filter[status]`}),` here is lowercased before use and accepts pseudo-filters like `,_jsx(_components.code,{children:`services`}),`, `,_jsx(_components.code,{children:`goods`}),`, `,_jsx(_components.code,{children:`inventory`}),`, or `,_jsx(_components.code,{children:`non-inventory`}),`, passed straight through to the underlying item model rather than independently validated.`]}),`\n`,_jsx(Heading,{level:`2`,id:`update-or-delete-an-item`,children:`Update or delete an item`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`PUT`}),` follows the same partial-patch rules as Clients, only submitted fields change (remembering that `,_jsx(_components.code,{children:`stock`}),` is the one exception that’s silently ignored). `,_jsx(_components.code,{children:`status`}),` is update-only: truthy is active, falsy is inactive.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -X`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` DELETE`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"https://app.billbooks.com/api/public-api/v1/items?id=118\"`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D7BA7D`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -H`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization: Bearer bb_live_your_key_here\"`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Deletion is blocked with `,_jsx(_components.code,{children:`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.`]}),`\n`,_jsx(Heading,{level:`2`,id:`what’s-next`,children:`What’s next`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/guides/create-and-send-an-invoice`,children:`Create and send an invoice`}),` to see `,_jsx(_components.code,{children:`item_id`}),` and stock deduction in action`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/guides/create-and-manage-estimates`,children:`Create and manage estimates`}),`, which reference the same catalog`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Build your item catalog","description":"Creating catalog items, and how stock tracking actually behaves","href":"/guides/build-your-item-catalog"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Create an item","slug":"create-an-item","depth":2,"children":[]},{"title":"How stock tracking actually works","slug":"how-stock-tracking-actually-works","depth":2,"children":[]},{"title":"List and filter items","slug":"list-and-filter-items","depth":2,"children":[]},{"title":"Update or delete an item","slug":"update-or-delete-an-item","depth":2,"children":[]},{"title":"What’s next","slug":"what’s-next","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"billbooks","siteName":"Billbooks Developers","title":"Build your item catalog - Billbooks Developers","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-18T03:23:57.916Z","originalFileLocation":"guides/build-your-item-catalog.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Creating catalog items, and how stock tracking actually behaves\">\u003cmeta data-mint-head name=\"application-name\" content=\"Billbooks Developers\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Build your item catalog - Billbooks Developers\">\u003cmeta data-mint-head property=\"og:description\" content=\"Creating catalog items, and how stock tracking actually behaves\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Billbooks Developers\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.billbooks.com/guides/build-your-item-catalog\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://billbooks.mintlify.site/_mintlify/api/og/v2?division=How-to+guides\u0026amp;title=Build+your+item+catalog\u0026amp;description=Creating+catalog+items%2C+and+how+stock+tracking+actually+behaves\u0026amp;theme=561a283edf63db09ec1b52d8\u0026amp;signature=12b78e273e838e2a2c8ef747975a9fc8f11a6d2f4b384c828760490283f88ec5\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Build your item catalog - Billbooks Developers\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Creating catalog items, and how stock tracking actually behaves\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://billbooks.mintlify.site/_mintlify/api/og/v2?division=How-to+guides\u0026amp;title=Build+your+item+catalog\u0026amp;description=Creating+catalog+items%2C+and+how+stock+tracking+actually+behaves\u0026amp;theme=561a283edf63db09ec1b52d8\u0026amp;signature=12b78e273e838e2a2c8ef747975a9fc8f11a6d2f4b384c828760490283f88ec5\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/billbooks/DtRNEGtcBglxM7tA/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Billbooks Developers\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#114a4d\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.billbooks.com/guides/build-your-item-catalog\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/guides/build-your-item-catalog.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.billbooks.com/#organization\",\"name\":\"Billbooks Developers\",\"url\":\"https://docs.billbooks.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/billbooks/jXmJmhNHvMwPE891/logo/light.svg?fit=max\u0026auto=format\u0026n=jXmJmhNHvMwPE891\u0026q=85\u0026s=881e2364171dc06515500a6ca77a20ef\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.billbooks.com#website\",\"name\":\"Billbooks Developers\",\"url\":\"https://docs.billbooks.com\",\"publisher\":{\"@id\":\"https://docs.billbooks.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.billbooks.com/guides/build-your-item-catalog#webpage\",\"url\":\"https://docs.billbooks.com/guides/build-your-item-catalog\",\"name\":\"Build your item catalog\",\"description\":\"Creating catalog items, and how stock tracking actually behaves\",\"dateModified\":\"2026-08-18T03:23:57.916Z\",\"isPartOf\":{\"@id\":\"https://docs.billbooks.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.billbooks.com/guides/build-your-item-catalog#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.billbooks.com/guides/build-your-item-catalog#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"How-to guides\",\"item\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Build your item catalog\",\"item\":\"https://docs.billbooks.com/guides/build-your-item-catalog\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.billbooks.com/guides/build-your-item-catalog#article\",\"headline\":\"Build your item catalog\",\"name\":\"Build your item catalog\",\"description\":\"Creating catalog items, and how stock tracking actually behaves\",\"url\":\"https://docs.billbooks.com/guides/build-your-item-catalog\",\"mainEntityOfPage\":{\"@id\":\"https://docs.billbooks.com/guides/build-your-item-catalog#webpage\"},\"dateModified\":\"2026-08-18T03:23:57.916Z\",\"publisher\":{\"@id\":\"https://docs.billbooks.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.billbooks.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Billbooks Developers\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Billbooks Developers\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/guides/build-your-item-catalog.md","siteName":"Billbooks Developers","nav":{"global":null,"tabs":[{"tab":"Guides","groups":[{"group":"Get Started","pages":[{"title":"Introduction","href":"/introduction"},{"title":"Authentication","href":"/authentication"},{"title":"Quickstart","href":"/quickstart"},{"title":"Rate Limits","href":"/rate-limits"},{"title":"Errors","href":"/errors"}]},{"group":"How-to guides","pages":[{"title":"Create and send an invoice","href":"/guides/create-and-send-an-invoice"},{"title":"Manage your client list","description":"Listing, filtering, creating, updating, and deleting clients","href":"/guides/manage-your-client-list"},{"title":"Build your item catalog","href":"/guides/build-your-item-catalog"},{"title":"Log expenses via API","description":"Recording expenses, how invoice-linking works, and a gap you should know about","href":"/guides/log-expenses-via-api"},{"title":"Create and manage estimates","href":"/guides/create-and-manage-estimates"}]}]},{"tab":"API Reference","pages":[{"title":"API Reference","href":"/reference/overview"}]}]},"basePath":"","title":"Build your item catalog - Billbooks Developers","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}