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 as customInfo.pol for Poland or customInfo.prt for 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 payload

eezi 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

  1. Map your data to the fields you send on this page.
  2. 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.
  3. Use that country's code lists for lines[].vat.code, lines[].unit and any exemption codes.
  4. Send the invoice with Create Invoice: Organisation API or Enterprise API.
  5. Read the response for the fields eezi returns, and handle a 202 Accepted as 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

NameTypeRequiredDescription
refstringYesYour invoice number. Must always be unique: never reuse a ref. Some countries limit its length or characters; see the country guide.
issuedstring (ISO 8601 date)YesIssue date of the invoice.
total.amountnumberYesTotal amount of the invoice, including tax. Must agree with the lines.
total.currencystringNoCurrency code, for example EUR. Defaults to the organisation's currency.
notesstringNoFree-text notes to show on the invoice.

Recipient (your customer)

NameTypeRequiredDescription
recipient.namestringYesLegal name of the company, or first name and surname of a person.
recipient.taxIdstringYesTax identification number. If the customer has none, use your country's placeholder (see Placeholder tax IDs).
recipient.address.line1stringNoStreet address, PO box or company name.
recipient.address.line2stringNoApartment, suite, unit or building.
recipient.address.citystringNoCity, town or district.
recipient.address.statestringNoState, province or region.
recipient.address.postalCodestringNoZIP or postal code.
recipient.address.countrystringYesCountry code, for example DEU.
recipient.contact.emailstringNoCustomer'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.

NameTypeRequiredDescription
sender.namestringConditionalRequired if you send sender. Legal name.
sender.taxIdstringConditionalRequired if you send sender. Tax identification number.
sender.address.line1stringNoStreet address, PO box or company name.
sender.address.line2stringNoApartment, suite, unit or building.
sender.address.citystringNoCity, town or district.
sender.address.statestringNoState, province or region.
sender.address.postalCodestringNoZIP or postal code.
sender.address.countrystringConditionalRequired if you send sender. Country code.
sender.contact.emailstringNoSender's email address.

Lines

NameTypeRequiredDescription
lines[].descriptionstringYesDescription of the goods or service.
lines[].quantitynumberYesQuantity.
lines[].unitstringNoUnit of measure. See Units of measure or the country guide's own list.
lines[].price.amountnumberYesUnit price, excluding tax.
lines[].vat.typestringYespercent: 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.amountnumberYesThe VAT rate or amount, depending on vat.type.
lines[].vat.codestringYesVAT category code. See VAT code classification or the country guide's own list.

Attachments

NameTypeRequiredDescription
attachments[].namestringConditionalRequired for each attachment. File name.
attachments[].contentTypestringConditionalRequired 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[].datastringConditionalRequired 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.

NameTypeDescription
idstringeezi's ID for the invoice. Use it to read the invoice, its status and its attachments.
orgIdstringThe organisation the invoice belongs to.
createdstring (ISO 8601)When eezi received the invoice.
modifiedstring (ISO 8601)When the invoice last changed, for example when its status changed. Use it for polling.
statusstringpending submission, pending response, success or error. See Document lifecycle.
typestringSent for invoices your organisation issued (AR), Received for invoices it received (AP).
routeRefstringThe reference assigned by the tax authority or network, once the invoice is accepted.
errorobjectPresent when status is error: name, message and, where available, description. See Common errors.

Deprecated fields

NameUse instead
invoiceSubmissionDateissued
taInvoiceRefrouteRef

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

Invoice - Generic.csv

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:

CountryPlaceholderNotes
France000000000 (9 zeros)Also send transactionType. See France e-Reporting.
Hungary0000000000 (10 zeros)When recipient.vatStatus is PRIVATE_PERSON.
Indonesia0000000000000000000000 (22 zeros)For identity types NIK, PASPOR or LAINNYA.
Poland0000000000 (10 zeros)
PortugalPT999999990
Romania0000000000000 (13 zeros)B2C transactions.
South Korea9999999999999 (13 nines)Foreign (non-domestic) recipients.
Taiwan0000000000 (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.

Credit notes follow the same pattern: start from the Generic credit note, then add the country's credit note guide.


Did this page help you?