# Finalize a draft invoice > The invoices.finalize operation: POST /api/v1/invoices/{id}/finalize in the REST API and the invoices_finalize tool in the MCP server. Issues a draft: it gets the next gap-free number of the brand's series, a fresh tax quote and its PDF, and can't change any more (spec §16.15, §18.2). 1. Lines in the §16.3 order: licensed items, metered usage, late usage, prorations, then invoice items. 2. Tax is quoted now with the customer's stored location evidence and tax IDs; a tax ID last checked more than 30 days ago is checked again with its register first. Proration lines are taxed at the rates of their change date. A sale Ownrecord can't tax with confidence is refused with a `tax_blocked` error and nothing changes. 3. The customer's credit balance in the invoice's currency is applied after tax (`creditApplied`); the rest is `amountDue`. When the balance covers everything the invoice is `paid` at once, else `open`. 4. The ledger books the receivable, the revenue (deferred for subscription periods) and the tax; the sale counts toward the registration thresholds on its tax date. For `send_invoice` the due date is fixed. A draft that totals zero (or less) isn't issued and takes no number: `invoice_total_zero` (spec §16.2). Emits `invoice.issued` and `invoice.finalized` (and `invoice.paid` when the credit balance paid it); the PDF is rendered right after. Dry-run it to see the number, the tax and the credit it would apply. ## At a glance - **REST:** `POST /api/v1/invoices/{id}/finalize` - **MCP tool:** `invoices_finalize` - **Operation ID:** `invoices.finalize` - **Scope:** Brand - **Permission:** `invoices:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `invoices:write` scope - **Since:** M5 ## Request ### Path parameters | Field | Type | Description | | ----- | ---------- | ------------------------- | | `id` | `inv_…` ID | The invoice ID (`inv_…`). | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ----------------- | -------------------- | -------- | ----------------------------------------------------------------------------- | | `expectedVersion` | integer (at least 1) | No | The `version` you read; a newer stored version fails with `version_conflict`. | ## Response `200 OK` with a JSON object: | Field | Type | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `inv_…` ID | | | `object` | `"invoice"` | | | `livemode` | boolean | | | `entityId` | `ent_…` ID | | | `brandId` | `brd_…` ID | | | `number` | string or null | The invoice number: gap-free per legal entity, mode, brand series and year (§18.2). Null for a draft: the number is taken at finalization. | | `numbering` | object or null | | | `customerId` | `cus_…` ID or null | | | `subscriptionId` | `sub_…` ID or null | | | `collectionMethod` | one of `charge_automatically`, `send_invoice` | | | `kind` | one of `invoice`, `receipt` or null | `invoice` (business customers) or `receipt` (the receipt-invoice consumers get); null for a draft. | | `status` | one of 9 values, e.g. `draft`, `pending_registration`, `issued` (all in the OpenAPI document) | `draft` → `open` (finalized) → `paid`, `void` or `uncollectible`. Checkout invoices are `issued` (paid at once), or `pending_registration`: a full invoice charged before the tax registration exists; the receipt went out and the formal invoice follows (§18.1). | | `language` | one of `en`, `de`, `fr`, `hr`, `it`, `es` or null | | | `issuedAt` | date-time or null | | | `issueDate` | string or null | The issue date in the seller's time zone. | | `taxPoint` | date-time or null | | | `taxPointDate` | string or null | The date of supply in the seller's time zone. | | `daysUntilDue` | integer or null | send_invoice: days from the issue date to the due date. | | `dueDate` | string or null | send_invoice: when payment is due (fixed at finalization). | | `seller` | object or null | | | `buyer` | object or null | | | `currency` | string | | | `lines` | array of object | | | `lines[].id` | string | The tax quote's line ID. | | `lines[].description` | string | | | `lines[].productId` | `prod_…` ID or null | | | `lines[].priceId` | `price_…` ID or null | | | `lines[].quantity` | integer | | | `lines[].taxCategoryId` | one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document) | | | `lines[].taxBehavior` | one of `inclusive`, `exclusive` | | | `lines[].unitAmount` | money | The net price of one unit (may be finer than the minor unit). | | `lines[].net` | money | | | `lines[].tax` | object | | | `lines[].tax.ratePpm` | string | Parts per million as a string (19% = "190000"). | | `lines[].tax.amount` | money | | | `lines[].tax.jurisdictionId` | string or null | | | `lines[].tax.regimeId` | string or null | | | `lines[].tax.decision` | one of `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`, `blocked` | What happened to the tax: `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`. | | `lines[].tax.rateKind` | one of `standard`, `reduced`, `super_reduced`, `parking`, `zero`, `exempt`, `not_taxable` or null | | | `lines[].tax.rateId` | string or null | | | `lines[].tax.pendingRegistration` | boolean | | | `lines[].gross` | money | | | `lines[].kind` | one of `licensed`, `metered`, `late_usage`, `proration`, `invoice_item` or null | Where the line came from (§16.3 order); null on checkout invoices. | | `lines[].period` | object or null | | | `lines[].subscriptionItemId` | string or null | | | `lines[].invoiceItemId` | `ii_…` ID or null | | | `lines[].discount` | money or null | What discounts took off the line before tax. | | `lines[].meteredQuantity` | string or null | A metered line's usage (its quantity is 1). | | `totals` | object or null | | | `taxCurrencyTotals` | object or null | The tax in the seller's tax currency when the invoice is in another one (§18.3). | | `creditApplied` | money or null | Taken from the customer's credit balance at finalization (§16.11). | | `amountDue` | money or null | What the customer pays: the gross total less the credit applied. Null on checkout invoices. | | `notes` | array of object | | | `notes[].code` | one of `reverse_charge`, `exempt`, `out_of_scope`, `registration_pending`, `oss_scheme` | | | `notes[].text` | string | The note as printed. | | `fieldCheck` | object or null | What the knowledge base's invoicing rules ask for that the invoice lacks (`missing`), and requirements Ownrecord can't check yet (`unchecked`). | | `pendingRegistration` | boolean | A full invoice with a line charged before the registration exists (§18.1). | | `paymentIds` | array of `pay_…` ID | | | `creditNoteIds` | array of `cn_…` ID | | | `ledgerTxnIds` | array of `txn_…` ID | | | `quoteId` | `tq_…` ID or null | The tax quote the invoice shows (null for a draft). | | `quoteIds` | array of `tq_…` ID | Every quote of the invoice: lines taxed at another date (prorations) have their own quote. | | `pdf` | object or null | Null for a draft: the PDF is rendered at finalization. | | `finalizedAt` | date-time or null | | | `paidAt` | date-time or null | | | `payment` | object or null | How the invoice was paid: `bank_transfer` (marked paid), `processor` (a card or debit payment) or `credit_balance`. | | `voidedAt` | date-time or null | | | `markedUncollectibleAt` | date-time or null | | | `emailedAt` | date-time or null | | | `sentAt` | date-time or null | When `invoices.send` last emailed the invoice. | | `draft` | object or null | A draft's lines before tax (tax is quoted at finalization); null once finalized. | | `metadata` | object | | | `version` | integer | Pass it as `expectedVersion` to refuse a change if the invoice changed. Rendering the PDF and emailing the invoice change it too. | | `createdAt` | date-time | | | `updatedAt` | date-time | | ## Examples ### A consulting invoice to a business in Austria, part paid from the credit balance Reverse charged; €200 of the customer's credit balance applied, €1,000 due in 14 days. ```http POST /api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yk/finalize Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "expectedVersion": 1 } ``` Response (`200`): ```json { "id": "inv_01m4tx5nj8emwbyf7y9vcf47yk", "object": "invoice", "livemode": false, "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "number": "GEN-2026-000131", "numbering": { "series": "GEN", "year": 2026, "seq": "131" }, "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym", "subscriptionId": null, "collectionMethod": "send_invoice", "kind": "invoice", "status": "open", "language": "en", "issuedAt": "2026-10-20T09:00:00.000Z", "issueDate": "2026-10-20", "taxPoint": "2026-10-20T09:00:00.000Z", "taxPointDate": "2026-10-20", "daysUntilDue": 14, "dueDate": "2026-11-03", "seller": { "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2", "legalName": "Acme Digital d.o.o.", "tradingName": null, "address": { "line1": "Ilica 1", "line2": null, "city": "Zagreb", "postalCode": "10000", "region": null, "country": "HR" }, "companyRegistryId": "080000001", "taxIds": [ { "type": "eu_vat", "value": "HR12345678901", "regimeId": null } ], "brand": { "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "name": "Genno", "primaryColor": "#0E6B5C", "accentColor": null, "supportEmail": "help@genno.example", "supportUrl": null }, "footerText": null }, "buyer": { "type": "b2b", "customerId": "cus_01m4tx5nj8emwbyf7y9vcf47ym", "name": "Alpen Apps GmbH", "email": "billing@alpen.example", "address": null, "country": "AT", "taxId": { "type": "eu_vat", "value": "ATU00000000", "country": "AT" } }, "currency": "EUR", "lines": [ { "id": "1", "description": "Implementation workshop (days)", "productId": "prod_01m4tx5nj8emwbyf7y9vcf47yr", "priceId": null, "quantity": 2, "taxCategoryId": "consulting_remote", "taxBehavior": "exclusive", "unitAmount": { "amount": "600000000", "currency": "EUR" }, "net": { "amount": "1200000000", "currency": "EUR" }, "tax": { "ratePpm": "0", "amount": { "amount": "0", "currency": "EUR" }, "jurisdictionId": "AT", "regimeId": "EU_OSS_UNION", "decision": "reverse_charge", "rateKind": null, "rateId": null, "pendingRegistration": false }, "gross": { "amount": "1200000000", "currency": "EUR" }, "kind": "invoice_item", "period": null, "subscriptionItemId": null, "invoiceItemId": "ii_01m4tx5nj8emwbyf7y9vcf47ys", "discount": null, "meteredQuantity": null } ], "totals": { "net": { "amount": "1200000000", "currency": "EUR" }, "tax": { "amount": "0", "currency": "EUR" }, "gross": { "amount": "1200000000", "currency": "EUR" }, "taxByRate": [ { "ratePpm": "0", "jurisdictionId": "AT", "regimeId": "EU_OSS_UNION", "decision": "reverse_charge", "net": { "amount": "1200000000", "currency": "EUR" }, "tax": { "amount": "0", "currency": "EUR" } } ] }, "taxCurrencyTotals": null, "creditApplied": { "amount": "200000000", "currency": "EUR" }, "amountDue": { "amount": "1000000000", "currency": "EUR" }, "notes": [ { "code": "reverse_charge", "text": "Prijenos porezne obveze (reverse charge) – čl. 17. st. 1. Zakona o PDV-u" } ], "fieldCheck": { "invoicingRuleIds": [], "missing": ["buyer_address"], "unchecked": [] }, "pendingRegistration": false, "paymentIds": [], "creditNoteIds": [], "ledgerTxnIds": ["txn_01m4tx5nj8emwbyf7y9vcf47yn"], "quoteId": "tq_01m4tx5nj8emwbyf7y9vcf47xr", "quoteIds": ["tq_01m4tx5nj8emwbyf7y9vcf47xr"], "pdf": { "status": "pending", "fileId": null, "sha256": null, "size": null, "templateVersion": null, "renderedAt": null, "url": "/api/v1/invoices/inv_01m4tx5nj8emwbyf7y9vcf47yk/pdf" }, "finalizedAt": "2026-10-20T09:00:00.000Z", "paidAt": null, "payment": null, "voidedAt": null, "markedUncollectibleAt": null, "emailedAt": null, "sentAt": null, "draft": null, "metadata": { "contract": "ENT-2026-07" }, "version": 2, "createdAt": "2026-10-20T08:30:00.000Z", "updatedAt": "2026-10-20T09:00:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | `id` is malformed, or the draft's due date is before the issue date. | Fix the fields listed in `details.issues` and send the request again. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | This brand has no such invoice in this mode (invoices belong to one brand and one mode). | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`invoice_status_invalid`](https://ownrecord.io/docs/reference/errors.md#invoice_status_invalid) | 409 | The invoice isn't a draft (it was finalized or voided). | Check the invoice's `status` (`details.status`) and what it still allows (`details.allowed_actions`). Drafts are edited and finalized; open invoices are sent, paid, voided or marked uncollectible; paid and void invoices don't change (corrections are credit notes). | | [`invoice_total_zero`](https://ownrecord.io/docs/reference/errors.md#invoice_total_zero) | 409 | The draft totals zero, or less (credits exceed charges): zero invoices aren't issued and take no number. | Add an item with an amount, or void the draft. Zero invoices aren't issued (spec §16.2): no number is taken for them. | | [`invoice_lines_invalid`](https://ownrecord.io/docs/reference/errors.md#invoice_lines_invalid) | 400 | A line can't be invoiced (`param` names it): e.g. more than 100 lines, or revenue booked at once without a product. | Describe every line of the quote exactly once, with a description of 1 to 500 characters and a whole-number quantity from 1 to 1,000,000. `param` names the line. | | [`customer_deleted`](https://ownrecord.io/docs/reference/errors.md#customer_deleted) | 400 | The draft's customer was deleted. | Create a new customer for this buyer. Deleted customers stay readable for the records they belong to, but can't be changed. | | [`registration_required`](https://ownrecord.io/docs/reference/errors.md#registration_required) | 422 | The fresh tax quote is blocked: the seller isn't registered where the sale is taxed (`details` has what to do). | Register the entity for the regime named in `details.regime` (see its prerequisites and deadline), or arm the jurisdiction once the prerequisites are done. The customer can join the waitlist meanwhile. | | [`evidence_conflict`](https://ownrecord.io/docs/reference/errors.md#evidence_conflict) | 422 | The customer's stored evidence doesn't confirm one place to tax the sale: e.g. a consumer, or a business without a valid VAT ID, in the EU with only its billing address (add a VAT ID, or a checkout's evidence). | Collect another piece of location evidence (billing address, card country, or the customer's confirmation of their country) and quote again. | | [`unsupported_tax_category`](https://ownrecord.io/docs/reference/errors.md#unsupported_tax_category) | 422 | A product's tax category has no place-of-supply rule there. | Sell it only where it is supported (e.g. domestically), or change the product's tax category if it was set wrongly. | | [`rate_unavailable`](https://ownrecord.io/docs/reference/errors.md#rate_unavailable) | 422 | There's no usable tax rate for a line on its tax date. | Sell to this jurisdiction later, once its rate is in the knowledge base and reviewed. In test mode, check that the jurisdiction is covered. | | [`jurisdiction_blocked`](https://ownrecord.io/docs/reference/errors.md#jurisdiction_blocked) | 422 | The customer's jurisdiction can't be sold to yet. | This jurisdiction isn't covered by usable tax knowledge for this seller. Contact support if you need to sell there. | | [`tax_id_unavailable`](https://ownrecord.io/docs/reference/errors.md#tax_id_unavailable) | 422 | A tax ID couldn't be checked and the brand doesn't sell until it is. | Try again in a few minutes. The tax-ID register (e.g. VIES) is unavailable, and this brand blocks business sales until the ID is verified. | | [`fx_rate_unavailable`](https://ownrecord.io/docs/reference/errors.md#fx_rate_unavailable) | 404 | A threshold in another currency needs ECB rates that aren't loaded. | Check the currency (the ECB publishes about 30) and the date. Rates are fetched every day after 16:00 CET; for a date with no rate yet, try again after the next publication. | | [`invoice_number_format_invalid`](https://ownrecord.io/docs/reference/errors.md#invoice_number_format_invalid) | 400 | The legal entity's number format can't make unique numbers; nothing was numbered. | Change the entity's invoice number format (Invoice settings) to a template with {series}, {seq} and, when the sequence restarts every year, {year}, e.g. {series}-{year}-{seq:06}. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The invoice changed since `expectedVersion`, or at the same moment; read it again and retry. | Fetch the object again and retry the change. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no brand (an org or entity key without `Ownrecord-Brand`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't change this brand's invoices (`invoices:write`: finance, owners and admins). | Ask an organization owner or admin for a role or scope that allows this action. | | [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403 | You have no live-mode access, so you can't use live invoices. | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).