E-invoice fields

This page is the mapping between what you send to POST /invoicing/documents and what ends up in the EN 16931 record, the CII XML and the PDF. Use it to map your data model before you integrate. The first part lists the request fields; the second walks the whole standard, business term by business term, and says what meetergo does with each.

Terminology: BT-n is a business term and BG-n a business group of the EN 16931 semantic model. Where the standard has no term for something meetergo prints on the PDF, the table says PDF only.

Request fields

Document (`POST /invoicing/documents` body)

Field	Type	Required	Becomes	Notes
`kind`	`offer` `order_confirmation` `invoice` `credit_note` `cancellation`	no, default `invoice`	BT-3 type code	`invoice` → 380, credit note → 381, cancellation → 384. Credit notes and cancellations are created from an invoice, not sent as `kind`.
`language`	`de` `en`	no, default from settings	PDF wording and email	Frozen with the document.
`issueDate`	ISO date	no, default today	BT-2	Also picks the number range year.
`dueDate`	ISO date	no	BT-9	Default `issueDate` + `defaultPaymentTermDays` from settings.
`deliveryDate`	ISO date	no, default `issueDate`	BT-72	Leistungs-/Lieferdatum.
`deliveryDateEnd`	ISO date	no	BT-73/BT-74 with `deliveryDate`	Sets a Leistungszeitraum instead of a single date.
`currency`	ISO 4217	no, default `EUR`	BT-5
`subject`	string ≤ 255	no	PDF only, email subject	Betreff.
`headText`	string	no	BT-22 note, PDF above the lines
`footText`	string	no	BT-22 note, PDF below the totals
`note`	string	no	BT-22 note	Free document note.
`buyer`	object	yes	BG-7 / BG-8	See below.
`lines[]`	array	for finalize	BG-25	See below. Full replacement on `PATCH`.
`taxTreatment`	enum	no, default `standard`	BT-118/BT-151 on every line, BT-120 wording	See the treatment table on Invoicing.
`paymentTermsNote`	string	no	BT-20	Skonto is prepended in the `#SKONTO#` syntax XRechnung requires.
`deliveryTermsNote`	string	no	PDF only	Lieferbedingungen.
`skontoPercent`, `skontoDays`	number	no	BT-20 (`#SKONTO#TAGE=7#PROZENT=2.00#`), PDF	Both or neither.
`totalDiscountPercent`	0 to 100	no	Compounded into every line’s BG-27 allowance	Gesamtrabatt; EN 16931 has no separate document discount here, see BG-20 below.
`internalContactUserId`	meetergo user id	no, required for XRechnung	BG-6 seller contact (BT-41/42/43), BT-34 seller electronic address	The user’s name, phone and email.
`depositPercent`	0.01 to 100	no	offers only	Anzahlung asked for when an offer is accepted.
`contactId`, `dealId`, `appointmentId`	uuid	no	none	Links into CRM and scheduling; not part of the e-invoice.

`buyer`

Field	Type	Required	Becomes
`name`	string ≤ 255	yes	BT-44
`addressLine1`	string ≤ 255	no	BT-50
`addressLine2`	string ≤ 255	no	BT-51
`postalCode`	string ≤ 16	no	BT-53
`city`	string ≤ 120	no	BT-52
`countryCode`	ISO 3166-1 alpha-2	no, default `DE`	BT-55
`email`	email	no, required for XRechnung	BT-49 electronic address (scheme `EM`); delivery address for `send`
`phone`	E.164	no	WhatsApp delivery only
`vatId`	string ≤ 32	no	BT-48 (scheme `VA`)
`reference`	string ≤ 64	no, required for XRechnung	BT-10 buyer reference (Leitweg-ID for B2G, otherwise the buyer’s PO or routing reference)

`lines[]`

Field	Type	Required	Becomes
`name`	string ≤ 255	yes	BT-153
`description`	plain text	no	BT-154
`descriptionHtml`	HTML (bold, italic, underline, links, lists)	no	PDF only; the plain text for BT-154 is derived from it
`quantity`	number, 3 decimals	yes	BT-129
`unitCode`	UN/ECE Rec. 20	no, default `C62`	BT-130. Common: `C62` piece, `HUR` hour, `DAY`, `MON` month, `KGM`, `MTK`, `LTR`, `MTR`
`unit`	string ≤ 32	no	PDF only, human label such as “Std.”
`unitPrice`	number, 4 decimals, net	yes	BT-146
`discountPercent`	0 to 100	no	BG-27: BT-136 amount, BT-137 base, BT-138 percent, BT-140 reason code `95`
`taxCategory`	`S` `Z` `E` `AE` `K` `G` `O`	no, default from settings	BT-151
`taxRate`	0 to 100	no, default from settings	BT-152
`productId`	uuid	no	copies name, price, unit and tax from the catalogue

Derived per line: BT-126 line identifier (the position), BT-131 line net amount (rounded to the cent after the allowance, satisfying BR-CO-10).

Seller side, from `PUT /invoicing/settings`

Setting	Becomes
`legalName` (fallback: company name)	BT-27, BT-85 account holder
`addressLine1`, `addressLine2`, `postalCode`, `city`, `countryCode`	BT-35, BT-36, BT-38, BT-37, BT-40
`vatId`	BT-31 (scheme `VA`)
`taxNumber`	BT-32 (scheme `FC`)
`iban`, `bic`, `bankName`; or a row in `/invoicing/bank-accounts` matched by currency	BG-16: BT-81 fixed `58` (SEPA credit transfer), BT-84 IBAN, BT-85, BT-86 BIC; bank name is PDF only
`smallBusiness`	forces category `E` with the § 19 UStG note
`defaultTaxRate`, `defaultPaymentTermDays`	defaults for `taxRate` and `dueDate`
`taxExemptionNotes`	replaces the BT-120 wording per category
`contactEmail`, `contactPhone`, `website`, `registerInfo`, `managingDirector`	PDF footer only
`logoFileAssetId`, `layout`	PDF letterhead only
number ranges (`/invoicing/number-ranges`)	BT-1 format per kind and year

At least one of vatId and taxNumber is mandatory to finalize.

Coverage of the EN 16931 model

Status legend:

Supported: you send it, it is in the XML and on the PDF.
Settings: comes from the seller’s invoicing settings.
Derived: meetergo computes it; you cannot and need not send it.
Planned: being built now for the next release; the proposed field name is given so you can map to it already.
On request: not offered today. Tell us which of these you need and we schedule them.

Document level

Term	Name	Status	Field
BT-1	Invoice number	Derived	from the number range
BT-2	Issue date	Supported	`issueDate`
BT-3	Type code	Derived	from `kind`: 380, 381, 384
BT-5	Currency	Supported	`currency`
BT-6	VAT accounting currency	On request
BT-7	VAT point date	On request
BT-8	VAT point date code	On request
BT-9	Payment due date	Supported	`dueDate`
BT-10	Buyer reference	Supported	`buyer.reference`
BT-11	Project reference	On request
BT-12	Contract reference	On request
BT-13	Purchase order reference	On request
BT-14	Sales order reference	On request
BT-15	Receiving advice reference	On request
BT-16	Despatch advice reference	On request
BT-17	Tender or lot reference	On request
BT-18	Invoiced object identifier	On request
BT-19	Buyer accounting reference	Planned	`costCenter` (Kostenstelle). Printed on the PDF info block and emitted as BT-19.
BT-20	Payment terms	Supported	`paymentTermsNote`, `skontoPercent`, `skontoDays`
BG-1 / BT-21, BT-22	Invoice note	Supported	`note`, `headText`, `footText` (BT-21 subject code not emitted)
BG-2 / BT-23	Business process	Derived	Peppol billing 01 for XRechnung
BG-2 / BT-24	Specification identifier	Derived	from `profile` at finalize
BG-3 / BT-25, BT-26	Preceding invoice reference	Derived	on credit notes and cancellations created from an invoice

Planned: custom fields. For internal references that have no business term (Profit Center, department, internal order number) the next release adds customFields: [{ "label": "Profit Center", "value": "4711" }] on the document. They are printed on the PDF info block and emitted in the XML as BT-22 notes in the form Profit Center: 4711, which every EN 16931 reader keeps. Kostenstelle and Debitornummer have real terms (BT-19, BT-46) and get their own fields.

Seller (BG-4, BG-5, BG-6)

Term	Name	Status	Field
BT-27	Seller name	Settings	`legalName`
BT-28	Seller trading name	On request
BT-29	Seller identifier	On request
BT-30	Seller legal registration identifier	On request	`registerInfo` is PDF only today
BT-31	Seller VAT identifier	Settings	`vatId`
BT-32	Seller tax registration identifier	Settings	`taxNumber`
BT-33	Seller additional legal information	On request
BT-34	Seller electronic address	Derived	email of `internalContactUserId`, scheme `EM`
BT-35, BT-36, BT-162	Address lines 1, 2, 3	Settings	`addressLine1`, `addressLine2` (line 3 on request)
BT-37	City	Settings	`city`
BT-38	Post code	Settings	`postalCode`
BT-39	Country subdivision	On request
BT-40	Country code	Settings	`countryCode`
BT-41, BT-42, BT-43	Seller contact name, phone, email	Supported	from `internalContactUserId`

Buyer (BG-7, BG-8, BG-9)

Term	Name	Status	Field
BT-44	Buyer name	Supported	`buyer.name`
BT-45	Buyer trading name	On request
BT-46	Buyer identifier	Planned	`buyer.customerNumber` (Debitornummer). Printed on the PDF and emitted as BT-46.
BT-47	Buyer legal registration identifier	On request
BT-48	Buyer VAT identifier	Supported	`buyer.vatId`
BT-49	Buyer electronic address	Supported	`buyer.email`, scheme `EM`
BT-50, BT-51, BT-163	Address lines 1, 2, 3	Supported	`buyer.addressLine1`, `buyer.addressLine2` (line 3 on request)
BT-52	City	Supported	`buyer.city`
BT-53	Post code	Supported	`buyer.postalCode`
BT-54	Country subdivision	On request
BT-55	Country code	Supported	`buyer.countryCode`
BT-56, BT-57, BT-58	Buyer contact name, phone, email	On request

Payee and tax representative (BG-10, BG-11, BG-12)

Term	Name	Status
BT-59, BT-60, BT-61	Payee name, identifier, legal registration	On request. The seller is always the payee.
BT-62 to BT-69, BT-164	Seller tax representative and address	On request

Delivery (BG-13, BG-14, BG-15)

Term	Name	Status	Field
BT-70	Deliver to party name	On request
BT-71	Deliver to location identifier	On request
BT-72	Actual delivery date	Supported	`deliveryDate`
BT-73, BT-74	Invoicing period start, end	Supported	`deliveryDate` + `deliveryDateEnd`
BT-75 to BT-80, BT-165	Deliver to address	On request

Payment instructions (BG-16 to BG-19)

Term	Name	Status	Field
BT-81	Payment means type code	Derived	`58` SEPA credit transfer when an IBAN is configured
BT-82	Payment means text	On request
BT-83	Remittance information	On request	the number is printed on the PDF and in the EPC QR code
BT-84	Payment account identifier (IBAN)	Settings	`iban` or bank account
BT-85	Payment account name	Settings	`legalName`
BT-86	Payment service provider identifier (BIC)	Settings	`bic`
BT-87, BT-88	Payment card	On request
BT-89, BT-90, BT-91	Direct debit mandate, creditor id, debited account	On request

Credit notes, cancellations and offers carry no payment instructions, since they never ask for money.

Document-level allowances and charges (BG-20, BG-21)

Term	Name	Status
BT-92 to BT-98	Document level allowance	On request. `totalDiscountPercent` exists but is compounded into each line’s BG-27 allowance, so the totals stay BR-CO-10 clean without a document-level group.
BT-99 to BT-105	Document level charge	On request. Shipping and similar go on a line today.

Totals (BG-22)

Term	Name	Status	Note
BT-106	Sum of line net amounts	Derived
BT-107	Sum of allowances on document level	Not emitted	always 0
BT-108	Sum of charges on document level	Not emitted	always 0
BT-109	Total amount without VAT	Derived
BT-110	Total VAT amount	Derived
BT-111	VAT in accounting currency	On request
BT-112	Total amount with VAT	Derived
BT-113	Paid amount	Derived	set when the invoice is born paid (a booking charged at checkout)
BT-114	Rounding amount	Not emitted
BT-115	Amount due for payment	Derived	BT-112 minus BT-113

VAT breakdown (BG-23)

Term	Name	Status
BT-116, BT-117, BT-118, BT-119	Taxable amount, tax amount, category, rate per group	Derived from the lines
BT-120	Exemption reason text	Derived from the category; override in `taxExemptionNotes`
BT-121	Exemption reason code	Not emitted

Additional supporting documents (BG-24)

Term	Name	Status
BT-122 to BT-125	Reference, description, external location, attached document	On request. Timesheets and similar cannot be embedded yet.

Invoice line (BG-25 to BG-32)

Term	Name	Status	Field
BT-126	Line identifier	Derived	position, 1-based
BT-127	Line note	On request
BT-128	Line object identifier	On request
BT-129	Invoiced quantity	Supported	`quantity`
BT-130	Quantity unit of measure	Supported	`unitCode`
BT-131	Line net amount	Derived
BT-132	Referenced purchase order line	On request
BT-133	Line buyer accounting reference	Planned	`lines[].costCenter`; falls back to the document’s `costCenter`
BT-134, BT-135	Line period	On request
BT-136 to BT-140	Line allowance	Supported	`discountPercent` (reason code `95`)
BT-141 to BT-145	Line charge	On request
BT-146	Item net price	Supported	`unitPrice`
BT-147, BT-148	Price discount, gross price	Not emitted	send the net price
BT-149, BT-150	Price base quantity and unit	Not emitted	price is always per one unit
BT-151	Line VAT category	Supported	`taxCategory`
BT-152	Line VAT rate	Supported	`taxRate`
BT-153	Item name	Supported	`name`
BT-154	Item description	Supported	`description`
BT-155	Item seller identifier	On request
BT-156	Item buyer identifier	On request
BT-157	Item standard identifier	On request
BT-158	Item classification identifier	On request
BT-159	Item country of origin	On request
BT-160, BT-161	Item attribute name, value	On request

What the validators check

Profile	Checked by	What passes
`zugferd-en16931`	meetergo emittability rules, then Mustang packaging and veraPDF	PDF/A-3 conformance with the CII XML attached as `factur-x.xml`, EN 16931 profile
`xrechnung-cii`	meetergo emittability rules, then the KoSIT validator (XRechnung 3.0 scenarios)	The Schematron the German public sector runs; the document is rejected with `400` if any rule fails

If you validate our XML yourself with the KoSIT validator, use the XRechnung profile. The ZUGFeRD EN 16931 XML carries the guideline urn:cen.eu:en16931:2017 and matches no XRechnung scenario, so KoSIT reports it as “not a known document type” rather than validating it.

Invoicing: the create, finalize, fetch flow
API Reference → Invoicing: every schema with types and limits

Get Started

Core Concepts

Webhooks

Components

Recipes

Best Practices

Request fields

Document (`POST /invoicing/documents` body)

`buyer`

`lines[]`

Seller side, from `PUT /invoicing/settings`

Coverage of the EN 16931 model

Document level

Seller (BG-4, BG-5, BG-6)

Buyer (BG-7, BG-8, BG-9)

Payee and tax representative (BG-10, BG-11, BG-12)

Delivery (BG-13, BG-14, BG-15)

Payment instructions (BG-16 to BG-19)

Document-level allowances and charges (BG-20, BG-21)

Totals (BG-22)

VAT breakdown (BG-23)

Additional supporting documents (BG-24)

Invoice line (BG-25 to BG-32)

What the validators check

​Request fields

​Document (POST /invoicing/documents body)

​buyer

​lines[]

​Seller side, from PUT /invoicing/settings

​Coverage of the EN 16931 model

​Document level

​Seller (BG-4, BG-5, BG-6)

​Buyer (BG-7, BG-8, BG-9)

​Payee and tax representative (BG-10, BG-11, BG-12)

​Delivery (BG-13, BG-14, BG-15)

​Payment instructions (BG-16 to BG-19)

​Document-level allowances and charges (BG-20, BG-21)

​Totals (BG-22)

​VAT breakdown (BG-23)

​Additional supporting documents (BG-24)

​Invoice line (BG-25 to BG-32)

​What the validators check

​Related

Request fields

Document (`POST /invoicing/documents` body)

`buyer`

`lines[]`

Seller side, from `PUT /invoicing/settings`

Coverage of the EN 16931 model

Document level

Seller (BG-4, BG-5, BG-6)

Buyer (BG-7, BG-8, BG-9)

Payee and tax representative (BG-10, BG-11, BG-12)

Delivery (BG-13, BG-14, BG-15)

Payment instructions (BG-16 to BG-19)

Document-level allowances and charges (BG-20, BG-21)

Totals (BG-22)

VAT breakdown (BG-23)

Additional supporting documents (BG-24)

Invoice line (BG-25 to BG-32)

What the validators check

Related