Finalize a draft invoice · Ownrecord docs

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).

Lines in the §16.3 order: licensed items, metered usage, late usage, prorations, then invoice items.
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.
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.
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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

A consulting invoice to a business in Austria, part paid from the credit balance#

Errors#