The full invoice lifecycle: creating, editing, and the side effects that come with each
The Invoices endpoint has full parity with the internal Billbooks app, not a stubbed subset. That means creating or editing an invoice through the API triggers the same real side effects a staff member creating one by hand would: stock gets deducted, expenses get linked, client balances move. This guide walks through all of it so nothing surprises you in production.
A few fields worth understanding before you script this:
no is your invoice number. It must be unique per organization. Reuse one and you get a 409 Conflict.
Each line needs either an item_id (pulled from your catalog) or a plain description, at least one of the two. qty must be greater than 0, rate must be 0 or more, and duplicate item_id values in the same request are rejected with 422.
subtotal, discount, taxtotal, and nettotal are always computed server-side from items. If you send those fields in the request body, they’re ignored. Only discount_type, discount_value, and shipping actually influence the computed totals.
status defaults to "draft" if you omit it. Set it to "sent" to send the invoice immediately.
What happens behind the scenes
Creating an invoice isn’t just a database insert. For each line item:
If the line resolves to an item_id whose catalog item has track_inventory turned on, stock is deducted and a ledger row is written recording the sale. See Build your item catalog for how track_inventory works.
If the line carries an expense_id, that expense is marked as invoiced and linked to this invoice. See Log expenses via API.
If status resolves to anything other than "draft", the client’s running balance is incremented by the invoice’s nettotal.
None of this is optional or togglable. If you’re building a script that creates draft invoices for review before sending, keep in mind the stock and balance effects only fire once you move status off "draft".
items is always a full replace on update, never a patch. Every line you want on the invoice after the edit has to be in the array, including ones that were already there. Any existing line you omit gets deleted, and its stock and expense-linking side effects are reversed as part of that deletion.
Every field other than items follows normal partial-patch rules: only what you submit changes. Changing status or client_id correctly reconciles the client balance delta, which is actually more complete than the internal app’s own edit screen (that one can’t change status or client at all).One restriction: through this endpoint, status can only be set to draft or sent. Moving an invoice to paid, partial, overdue, void, or recurring is rejected with 422, those states are only reachable from inside the main app (typically as the result of a recorded payment).
Deletion is blocked with 409 Conflict if the invoice has any recorded payment, which is actually a stricter guard than the internal app’s own delete function has. If the delete succeeds, all stock and expense-linking side effects from that invoice are reversed line by line, and if the invoice wasn’t a draft, the client’s balance is decremented by the invoice’s balance.
Errors for what a 409 or 422 response looks like in full
{"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/create-and-send-an-invoice","slug":"/guides/create-and-send-an-invoice","pageMetadata":{"title":"Create and send an invoice","description":"The full invoice lifecycle: creating, editing, and the side effects that come with each","href":"/guides/create-and-send-an-invoice"},"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: \"The full invoice lifecycle: creating, editing, and the side effects that come with each\"\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,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`The Invoices endpoint has full parity with the internal Billbooks app, not a stubbed subset. That means creating or editing an invoice through the API triggers the same real side effects a staff member creating one by hand would: stock gets deducted, expenses get linked, client balances move. This guide walks through all of it so nothing surprises you in production.`}),`\n`,_jsx(Heading,{level:`2`,id:`create-an-invoice`,children:`Create an invoice`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`22`,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:`22`,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/invoices`}),_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:` \"client_id\": 4821,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"date\": \"2026-08-18\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"no\": \"INV-1042\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"due_terms\": \"net_30\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"status\": \"sent\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"items\": [`})}),`\n`,_jsx(_components.span,{className:`line`,children:_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:` \"item_id\": 118,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"qty\": 2,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"rate\": 450`})}),`\n`,_jsx(_components.span,{className:`line`,children:_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:` {`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"description\": \"One-off consulting call\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"qty\": 1,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"rate\": 200`})}),`\n`,_jsx(_components.span,{className:`line`,children:_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:` ]`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`A few fields worth understanding before you script this:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`no`}),` is your invoice number. It must be unique per organization. Reuse one and you get a `,_jsx(_components.code,{children:`409 Conflict`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`Each line needs either an `,_jsx(_components.code,{children:`item_id`}),` (pulled from your catalog) or a plain `,_jsx(_components.code,{children:`description`}),`, at least one of the two. `,_jsx(_components.code,{children:`qty`}),` must be greater than 0, `,_jsx(_components.code,{children:`rate`}),` must be 0 or more, and duplicate `,_jsx(_components.code,{children:`item_id`}),` values in the same request are rejected with `,_jsx(_components.code,{children:`422`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`subtotal`}),`, `,_jsx(_components.code,{children:`discount`}),`, `,_jsx(_components.code,{children:`taxtotal`}),`, and `,_jsx(_components.code,{children:`nettotal`}),` are always computed server-side from `,_jsx(_components.code,{children:`items`}),`. If you send those fields in the request body, they’re ignored. Only `,_jsx(_components.code,{children:`discount_type`}),`, `,_jsx(_components.code,{children:`discount_value`}),`, and `,_jsx(_components.code,{children:`shipping`}),` actually influence the computed totals.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`status`}),` defaults to `,_jsx(_components.code,{children:`\"draft\"`}),` if you omit it. Set it to `,_jsx(_components.code,{children:`\"sent\"`}),` to send the invoice immediately.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`what-happens-behind-the-scenes`,children:`What happens behind the scenes`}),`\n`,_jsx(_components.p,{children:`Creating an invoice isn’t just a database insert. For each line item:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`If the line resolves to an `,_jsx(_components.code,{children:`item_id`}),` whose catalog item has `,_jsx(_components.code,{children:`track_inventory`}),` turned on, stock is deducted and a ledger row is written recording the sale. See `,_jsx(_components.a,{href:`/guides/build-your-item-catalog`,children:`Build your item catalog`}),` for how `,_jsx(_components.code,{children:`track_inventory`}),` works.`]}),`\n`,_jsxs(_components.li,{children:[`If the line carries an `,_jsx(_components.code,{children:`expense_id`}),`, that expense is marked as invoiced and linked to this invoice. See `,_jsx(_components.a,{href:`/guides/log-expenses-via-api`,children:`Log expenses via API`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`If `,_jsx(_components.code,{children:`status`}),` resolves to anything other than `,_jsx(_components.code,{children:`\"draft\"`}),`, the client’s running balance is incremented by the invoice’s `,_jsx(_components.code,{children:`nettotal`}),`.`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`None of this is optional or togglable. If you’re building a script that creates draft invoices for review before sending, keep in mind the stock and balance effects only fire once you move status off `,_jsx(_components.code,{children:`\"draft\"`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`editing-an-invoice`,children:`Editing an invoice`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`9`,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:`9`,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:` PUT`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://app.billbooks.com/api/public-api/v1/invoices`}),_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:` \"id\": 9931,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"items\": [`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` { \"item_id\": 118, \"qty\": 3, \"rate\": 450 }`})}),`\n`,_jsx(_components.span,{className:`line`,children:_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:` }'`})}),`\n`]})})}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`items`}),` is always a full replace on update, never a patch. Every line you want on the invoice after the edit has to be in the array, including ones that were already there. Any existing line you omit gets deleted, and its stock and expense-linking side effects are reversed as part of that deletion.`]})}),`\n`,_jsxs(_components.p,{children:[`Every field other than `,_jsx(_components.code,{children:`items`}),` follows normal partial-patch rules: only what you submit changes. Changing `,_jsx(_components.code,{children:`status`}),` or `,_jsx(_components.code,{children:`client_id`}),` correctly reconciles the client balance delta, which is actually more complete than the internal app’s own edit screen (that one can’t change status or client at all).`]}),`\n`,_jsxs(_components.p,{children:[`One restriction: through this endpoint, `,_jsx(_components.code,{children:`status`}),` can only be set to `,_jsx(_components.code,{children:`draft`}),` or `,_jsx(_components.code,{children:`sent`}),`. Moving an invoice to `,_jsx(_components.code,{children:`paid`}),`, `,_jsx(_components.code,{children:`partial`}),`, `,_jsx(_components.code,{children:`overdue`}),`, `,_jsx(_components.code,{children:`void`}),`, or `,_jsx(_components.code,{children:`recurring`}),` is rejected with `,_jsx(_components.code,{children:`422`}),`, those states are only reachable from inside the main app (typically as the result of a recorded payment).`]}),`\n`,_jsx(Heading,{level:`2`,id:`deleting-an-invoice`,children:`Deleting an invoice`}),`\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/invoices?id=9931\"`}),_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 invoice has any recorded payment, which is actually a stricter guard than the internal app’s own delete function has. If the delete succeeds, all stock and expense-linking side effects from that invoice are reversed line by line, and if the invoice wasn’t a draft, the client’s balance is decremented by the invoice’s balance.`]}),`\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/manage-your-client-list`,children:`Manage your client list`}),` to look up or create the `,_jsx(_components.code,{children:`client_id`}),` you’re invoicing`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/guides/build-your-item-catalog`,children:`Build your item catalog`}),` so line items can reference `,_jsx(_components.code,{children:`item_id`}),` and keep stock in sync`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/errors`,children:`Errors`}),` for what a `,_jsx(_components.code,{children:`409`}),` or `,_jsx(_components.code,{children:`422`}),` response looks like in full`]}),`\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":"Create and send an invoice","description":"The full invoice lifecycle: creating, editing, and the side effects that come with each","href":"/guides/create-and-send-an-invoice"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Create an invoice","slug":"create-an-invoice","depth":2,"children":[]},{"title":"What happens behind the scenes","slug":"what-happens-behind-the-scenes","depth":2,"children":[]},{"title":"Editing an invoice","slug":"editing-an-invoice","depth":2,"children":[]},{"title":"Deleting an invoice","slug":"deleting-an-invoice","depth":2,"children":[]},{"title":"What’s next","slug":"what’s-next","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"billbooks","siteName":"Billbooks Developers","title":"Create and send an invoice - Billbooks Developers","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-08-18T03:23:57.917Z","originalFileLocation":"guides/create-and-send-an-invoice.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=\"The full invoice lifecycle: creating, editing, and the side effects that come with each\">\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=\"Create and send an invoice - Billbooks Developers\">\u003cmeta data-mint-head property=\"og:description\" content=\"The full invoice lifecycle: creating, editing, and the side effects that come with each\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Billbooks Developers\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.billbooks.com/guides/create-and-send-an-invoice\">\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=Create+and+send+an+invoice\u0026amp;description=The+full+invoice+lifecycle%3A+creating%2C+editing%2C+and+the+side+effects+that+come+with+each\u0026amp;theme=561a283edf63db09ec1b52d8\u0026amp;signature=14904a0d38c9719158d757e1b7894f627c1c0fab18cd3d7bf43befe3a274e698\">\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=\"Create and send an invoice - Billbooks Developers\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"The full invoice lifecycle: creating, editing, and the side effects that come with each\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://billbooks.mintlify.site/_mintlify/api/og/v2?division=How-to+guides\u0026amp;title=Create+and+send+an+invoice\u0026amp;description=The+full+invoice+lifecycle%3A+creating%2C+editing%2C+and+the+side+effects+that+come+with+each\u0026amp;theme=561a283edf63db09ec1b52d8\u0026amp;signature=14904a0d38c9719158d757e1b7894f627c1c0fab18cd3d7bf43befe3a274e698\">\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/create-and-send-an-invoice\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/guides/create-and-send-an-invoice.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/create-and-send-an-invoice#webpage\",\"url\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice\",\"name\":\"Create and send an invoice\",\"description\":\"The full invoice lifecycle: creating, editing, and the side effects that come with each\",\"dateModified\":\"2026-08-18T03:23:57.917Z\",\"isPartOf\":{\"@id\":\"https://docs.billbooks.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Billbooks Developers\",\"item\":\"https://docs.billbooks.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create and send an invoice\",\"item\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice#article\",\"headline\":\"Create and send an invoice\",\"name\":\"Create and send an invoice\",\"description\":\"The full invoice lifecycle: creating, editing, and the side effects that come with each\",\"url\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice\",\"mainEntityOfPage\":{\"@id\":\"https://docs.billbooks.com/guides/create-and-send-an-invoice#webpage\"},\"dateModified\":\"2026-08-18T03:23:57.917Z\",\"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/create-and-send-an-invoice.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","description":"The error envelope shape and what each error code means","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","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":"Create and send an invoice - Billbooks Developers","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}