Invoices

Every sale that's paid at checkout issues a tax document right away: an invoice for a business customer, or a receipt (a receipt-invoice showing the tax charged) for a consumer. Ownrecord issues one for every customer, even where the law doesn't require it for consumers.

You can also invoice a customer yourself, outside any subscription: setup fees, consulting, enterprise contracts paid by bank transfer. Subscriptions bill through the same invoices.

An invoice shows exactly the tax of its tax quote: its lines, rates, jurisdictions and regimes. Invoices are never recomputed, and an issued invoice never changes. A correction is a credit note.

Lifecycle#

draft → open → paid, void or uncollectible (and uncollectible → paid). Paid invoices aren't voided: they're corrected with a credit note when you refund them (partially_credited, then credited).

Finalizing a draft#

Finalizing issues the invoice:

1. Lines in order: plan charges for the new period, metered usage for the period that ended, late usage, prorations, then one-off items. Discounts are on the lines.
2. Tax, 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 the day the change was made. When Ownrecord can't tax the sale with confidence, finalizing is refused with the tax_blocked reason and nothing changes. A consumer needs location evidence from a checkout; a billing country alone isn't enough. That includes a business without a valid tax ID: see Business customers without a valid VAT ID.
3. Credit balance: the customer's credit balance in the invoice's currency is applied to the total after tax (creditApplied); the rest is the amountDue. When the balance covers everything, the invoice is paid at once.
4. Number and PDF: the next number of the brand's series, then the PDF.
5. Ledger: the brand's receivables, the revenue (deferred for subscription periods) and the tax. The sale counts toward your registration thresholds on its tax date.

A draft that totals zero isn't issued and takes no number (invoice_total_zero).

Invoicing a customer yourself#

1. Create a draft for a customer of the brand: in the console, Invoices → New invoice, or invoices.create. Choose the currency and how it's paid: sent for payment by bank transfer (default), or charged to the customer's payment method.
2. Add items: an active one-time price, or any active product with the amount you type (excluding or including tax), times a quantity. Each item books its revenue to its product.
3. Finalize it.
4. Send it (invoices.send): the customer gets an email in the invoice's language with the amount due, the due date, your bank details (account holder, IBAN, BIC, bank) and the payment reference, which is the invoice number, with a link to the PDF. Your legal entity needs bank transfer details in its invoice settings. The email also links to the invoice's hosted page, where the customer can pay by card. Reminders follow before and after the due date.
5. Record the payment: when the transfer arrives, Mark paid with the date it arrived and the reference on your bank statement (invoices.mark_paid), or import the statement and let Ownrecord match it. The ledger moves the amount from your receivables to the entity's bank account, and a past-due subscription becomes active again.

The due date is the issue date plus the draft's payment term (daysUntilDue, 14 days by default), or a fixed dueDate, fixed when the invoice is finalized.

Business customers without a valid VAT ID#

Only a valid tax ID makes a sale business-to-business. A business whose VAT ID is missing, invalid or not yet confirmed by its register is taxed as a consumer, and in the EU a consumer's country needs two pieces of location evidence that agree. A customer you created through the API with only a billing address has one, so finalizing its invoice is refused with evidence_conflict (one evidence item) and the draft stays as it was. Before you finalize, give Ownrecord one of these:

• A validated tax ID: add the business's VAT ID (customers.tax_ids.add, or taxIds on customers.create). Once its register confirms it, the invoice is business-to-business (reverse charge across borders) and the billing address is enough.
• A second piece of evidence: a purchase by the same customer through a hosted checkout stores its IP address and card country with its billing address, and finalizing uses that evidence. Finalize after the customer has bought once.

Invoice items#

Invoice items are lines waiting for an invoice. An item created for a draft is part of that draft; an item created without one is pending: it's billed on the customer's next subscription invoice, or on a draft created with includePendingItems. Items can be deleted while they're pending or on a draft; once the invoice is finalized they're part of its record.

Customer credit balance#

Each customer has a credit balance per currency: proration credits from downgrades, goodwill credits and overpayments. It's applied automatically to the customer's next invoices, after tax, before they're charged or sent. It isn't the usage wallet.

Owners and admins adjust it with a reason (customers.credit_balance.adjustments.create): add credit, or take unused credit back. It never goes below zero. Voiding an open invoice gives back the credit it used. Every change emits customer.credit_balance.updated.

Numbers#

Invoice numbers are gap-free. Each brand has its own series (for example GEN for one brand and OWN for another), numbered within its legal entity:

• per legal entity, per mode (test numbers never touch live ones), per series, and per year when the entity restarts its sequence every year;
• from the entity's number template, {series}-{year}-{seq:06} by default, so the first invoice of 2026 is GEN-2026-000001.

A number is taken in the same database transaction that stores the invoice (at checkout, the transaction that records the payment; for a draft, its finalization), so a sale that fails at any step never uses one. Drafts take no number. The template may use {series}, {year}, {seq} and {seq:NN} (padded to NN digits). It must contain {series} and {seq}, and {year} when the sequence restarts every year, so numbers stay unique. The year is the issue year in the entity's time zone.

What an invoice shows#

• the issue date, and the date of supply when it differs;
• the number;
• the seller's legal name, address, company number and tax ID, plus the registration number of the regime the tax is due under, once you're registered;
• the customer's name, address and, for a business, the tax ID the sale was quoted with;
• each line with its description, quantity, net unit price, tax rate and tax;
• net and tax per rate, and the totals;
• the tax in the seller's own currency when the invoice is in another one, at the ECB reference rate of the tax point;
• legal notes.

The invoice language is the customer's (from checkout or the customer's language) when invoices support it (English, German, French, Croatian, Italian and Spanish), else the entity's invoice language. An entity with a second invoice language (invoiceSettings.bilingual) gets bilingual invoices: every label in the invoice's language and the second one ("Račun / Invoice"). See Languages.

Legal notes#

Sales during a grace period#

A consumer gets the receipt at once, with the "registration pending" note. A business invoice charged at checkout before the registration exists has the status pending_registration: the customer gets the receipt now, and the formal invoice follows once the registration number is issued. A finalized invoice in the same situation stays open with pendingRegistration: true.

Required details#

The knowledge base lists, per country, what an invoice must contain. Ownrecord checks every invoice against those rules and lists what's missing in fieldCheck.missing, for example a business customer's address. Collect it at checkout, or on the customer before you finalize. Requirements Ownrecord can't check yet, such as fiscal codes of a fiscalized receipt, are listed in fieldCheck.unchecked.

PDF#

Right after an invoice is issued, Ownrecord renders its PDF with your brand's name and colors and your entity's legal details, stores it, and records its SHA-256. The PDF is rendered from the invoice as issued, with a versioned template, so it never changes: rendering it again gives the same bytes, and a stored file that doesn't match its hash is never served. Drafts have no PDF.

• API: GET /api/v1/invoices/{id}/pdf with your API key returns the PDF (application/pdf; the ETag is its SHA-256). Until it's rendered, usually within seconds, the call answers invoice_pdf_not_ready; retry shortly. invoices.get shows pdf.status.
• Console: open the brand, choose Invoices, open an invoice and choose Download PDF.
• MCP: invoices_pdf returns the file's details and download URL.

Email#

Once the PDF of a checkout invoice exists, the customer gets an email in the invoice's language with the total and a link to download the PDF. Invoices sent for payment are emailed by invoices.send, with the payment details. The link works without signing in and doesn't expire, like an attachment would. Until customers have the customer portal, it's their copy of the invoice.

Events#

Your webhooks receive them; the event reference has their payloads.

In the API#

Mark paid, mark uncollectible, void and credit balance adjustments are financial actions: your organization's approval policy can require a second person. Dry-run them first.