Generic
The generic invoice model is the starting point for every eezi integration. Every invoice, in every country, is built on the fields on this page. Build your mapping to this model first; supporting a new country then means adding a few fields, not starting again.
How the generic model and country guides fit together
Your invoice = generic fields (this page)
+ country rules and extra fields (your country's guide)Each country guide only lists what is different from this page:
- Changes to generic fields: optional fields on this page that become required in that country, or extra format rules (for example, a maximum length for
ref). - Country-specific fields: extra fields, usually under
customInfo.<country>, such ascustomInfo.polfor Poland orcustomInfo.prtfor Portugal. Three-letter country codes are used throughout. - Code lists: the VAT codes, units and exemption codes accepted in that country.
Anything a country guide does not mention works exactly as described here.
The country comes from the organisation, not the payloadeezi applies a country's rules based on the organisation you send the invoice to. A Polish organisation applies the Poland rules; a German organisation applies the Germany rules. You never set the country in the invoice itself. Send each invoice to the organisation of the entity that issues it.
How to build an invoice
- Map your data to the fields you send on this page.
- Open the guide for the organisation's country (see Country guides) and add what it lists under Changes to generic fields and Country-specific fields.
- Use that country's code lists for
lines[].vat.code,lines[].unitand any exemption codes. - Send the invoice with Create Invoice: Organisation API or Enterprise API.
- Read the response for the fields eezi returns, and handle a
202 Acceptedas described in Asynchronous responses.
Formats used throughout: dates in ISO 8601 (UTC), currencies in ISO 4217, countries in ISO 3166-1 alpha-3, UTF-8 text, and up to two decimal places. Rounding rules are on Data models.
Schema
interface Invoice {
// Fields you send
ref: string;
issued: string;
recipient: Recipient;
sender?: Party;
total: {
amount: number;
currency?: string;
};
lines: InvoiceLine[];
attachments?: Attachment[];
notes?: string;
// Fields eezi returns
id: string;
orgId: string;
created: string;
modified: string;
status: 'pending submission' | 'pending response' | 'success' | 'error';
type: 'Sent' | 'Received';
routeRef?: string;
error?: {
name: string;
message: string;
description?: string;
};
}
interface Recipient {
name: string;
taxId: string;
address: Address;
contact?: {
email?: string;
};
}
interface Party {
name: string;
taxId: string;
address: Address;
contact?: {
email?: string;
};
}
interface Address {
line1?: string;
line2?: string;
city?: string;
state?: string;
postalCode?: string;
country: string;
}
interface InvoiceLine {
description: string;
quantity: number;
unit?: UnitsOfMeasure;
price: {
amount: number;
};
vat: {
type: 'fixed' | 'percent';
amount: number;
code: TaxCode;
};
}
interface Attachment {
name: string;
contentType:
| 'application/pdf'
| 'image/png'
| 'image/jpeg'
| 'text/csv'
| 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
| 'application/vnd.oasis.opendocument.spreadsheet';
data: string;
}Fields you send
Required is the generic rule. A country guide can make an optional field required for that country.
Document
| Name | Type | Required | Description |
|---|---|---|---|
ref | string | Yes | Your invoice number. Must always be unique: never reuse a ref. Some countries limit its length or characters; see the country guide. |
issued | string (ISO 8601 date) | Yes | Issue date of the invoice. |
total.amount | number | Yes | Total amount of the invoice, including tax. Must agree with the lines. |
total.currency | string | No | Currency code, for example EUR. Defaults to the organisation's currency. |
notes | string | No | Free-text notes to show on the invoice. |
Recipient (your customer)
| Name | Type | Required | Description |
|---|---|---|---|
recipient.name | string | Yes | Legal name of the company, or first name and surname of a person. |
recipient.taxId | string | Yes | Tax identification number. If the customer has none, use your country's placeholder (see Placeholder tax IDs). |
recipient.address.line1 | string | No | Street address, PO box or company name. |
recipient.address.line2 | string | No | Apartment, suite, unit or building. |
recipient.address.city | string | No | City, town or district. |
recipient.address.state | string | No | State, province or region. |
recipient.address.postalCode | string | No | ZIP or postal code. |
recipient.address.country | string | Yes | Country code, for example DEU. |
recipient.contact.email | string | No | Customer's email address. |
Sender (only to override your organisation's details)
You normally leave sender out: eezi uses the details of the organisation you send the invoice to. Send it only to override those details, or where a country guide asks for it (for example self-billed invoices). On received invoices (type: Received), eezi fills sender with the supplier's details.
| Name | Type | Required | Description |
|---|---|---|---|
sender.name | string | Conditional | Required if you send sender. Legal name. |
sender.taxId | string | Conditional | Required if you send sender. Tax identification number. |
sender.address.line1 | string | No | Street address, PO box or company name. |
sender.address.line2 | string | No | Apartment, suite, unit or building. |
sender.address.city | string | No | City, town or district. |
sender.address.state | string | No | State, province or region. |
sender.address.postalCode | string | No | ZIP or postal code. |
sender.address.country | string | Conditional | Required if you send sender. Country code. |
sender.contact.email | string | No | Sender's email address. |
Lines
| Name | Type | Required | Description |
|---|---|---|---|
lines[].description | string | Yes | Description of the goods or service. |
lines[].quantity | number | Yes | Quantity. |
lines[].unit | string | No | Unit of measure. See Units of measure or the country guide's own list. |
lines[].price.amount | number | Yes | Unit price, excluding tax. |
lines[].vat.type | string | Yes | percent: vat.amount is a rate, for example 20 for 20%. fixed: vat.amount is the tax amount for the whole line. Both apply per line, not per unit. |
lines[].vat.amount | number | Yes | The VAT rate or amount, depending on vat.type. |
lines[].vat.code | string | Yes | VAT category code. See VAT code classification or the country guide's own list. |
Attachments
| Name | Type | Required | Description |
|---|---|---|---|
attachments[].name | string | Conditional | Required for each attachment. File name. |
attachments[].contentType | string | Conditional | Required for each attachment. One of application/pdf, image/png, image/jpeg, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.oasis.opendocument.spreadsheet. |
attachments[].data | string | Conditional | Required for each attachment. File content, Base64 encoded, up to 1 MB. |
Fields eezi returns
These fields are set by eezi. Leave them out of your request; any value you send is ignored.
| Name | Type | Description |
|---|---|---|
id | string | eezi's ID for the invoice. Use it to read the invoice, its status and its attachments. |
orgId | string | The organisation the invoice belongs to. |
created | string (ISO 8601) | When eezi received the invoice. |
modified | string (ISO 8601) | When the invoice last changed, for example when its status changed. Use it for polling. |
status | string | pending submission, pending response, success or error. See Document lifecycle. |
type | string | Sent for invoices your organisation issued (AR), Received for invoices it received (AP). |
routeRef | string | The reference assigned by the tax authority or network, once the invoice is accepted. |
error | object | Present when status is error: name, message and, where available, description. See Common errors. |
Deprecated fields
| Name | Use instead |
|---|---|
invoiceSubmissionDate | issued |
taInvoiceRef | routeRef |
Example
A minimal generic invoice. For a real country, add the fields from its guide.
{
"ref": "INV-2026-0001",
"issued": "2026-11-12",
"recipient": {
"name": "Acme Trading Ltd",
"taxId": "GB123456789",
"address": {
"line1": "1 High Street",
"city": "London",
"postalCode": "EC1A 1AA",
"country": "GBR"
},
"contact": { "email": "[email protected]" }
},
"total": { "amount": 1200.00, "currency": "EUR" },
"lines": [
{
"description": "Consulting services",
"quantity": 10,
"unit": "HUR",
"price": { "amount": 100.00 },
"vat": { "type": "percent", "amount": 20, "code": "S" }
}
]
}The response is the stored invoice, with the fields eezi returns added:
{
"id": "01JTGZHW3Y0Y975DHHT3E9AK5X",
"orgId": "01JS98K5R8P83RTTQ8XBX4WTNE",
"created": "2026-11-12T09:42:48.446Z",
"modified": "2026-11-12T09:42:48.446Z",
"status": "success",
"type": "Sent",
"routeRef": "mck_01JTGZHWC2JVEM6TT2816MZ96Z",
"ref": "INV-2026-0001",
"...": "the fields you sent"
}Example CSV file
Placeholder tax IDs
recipient.taxId is always required. When your customer has no tax ID (for example, a consumer), use the placeholder for the organisation's country:
| Country | Placeholder | Notes |
|---|---|---|
| France | 000000000 (9 zeros) | Also send transactionType. See France e-Reporting. |
| Hungary | 0000000000 (10 zeros) | When recipient.vatStatus is PRIVATE_PERSON. |
| Indonesia | 0000000000000000000000 (22 zeros) | For identity types NIK, PASPOR or LAINNYA. |
| Poland | 0000000000 (10 zeros) | |
| Portugal | PT999999990 | |
| Romania | 0000000000000 (13 zeros) | B2C transactions. |
| South Korea | 9999999999999 (13 nines) | Foreign (non-domestic) recipients. |
| Taiwan | 0000000000 (10 zeros) | B2C transactions. |
For any other country, check its guide.
Country guides
Each guide lists only the changes to this page and the country's own fields.
| Region | Guides |
|---|---|
| Europe | Belgium · Croatia · Denmark · France e-Invoicing · France e-Reporting · Germany · Greece · Hungary · Italy · Poland · Portugal · Romania · Spain SII Issued · Spain SII Received · Spain Verifactu |
| Peppol network | Peppol |
| Asia Pacific | Australia · China · India · Indonesia · Japan · Malaysia · New Zealand · South Korea · Taiwan |
| Middle East and Africa | Egypt · Jordan · Kenya · Nigeria · Saudi Arabia · Turkey · United Arab Emirates |
| Americas | Mexico · Mexico Archiving |
| Other | Legacy data import |
Credit notes follow the same pattern: start from the Generic credit note, then add the country's credit note guide.
Updated 5 days ago