Which BT fields does the faktoora API support?
Overview of the EN 16931 business terms (BT fields) covered by the faktoora invoice API, with API field and required status.
The faktoora API generates electronic invoices (XRechnung, ZUGFeRD, Peppol) according to the European standard EN 16931. This standard describes every possible invoice detail as a so-called "business term", BT for short, with a fixed number, for example BT-1 for the invoice number. In the faktoora API reference, the matching BT number is noted in the field description of every field that corresponds to such a business term.
Where the BT fields are in the API
When you create an invoice via POST /invoices, you send an Invoice object. The BT fields in it are spread across several areas:
- Invoice header: directly on the
Invoiceobject (invoice number, date, invoice type, currency, references) seller: seller details (name, address, VAT ID)buyer: buyer details (name, address, VAT ID, references)invoiceItems: invoice line items, each with aproductobject (description, quantity, unit price, tax rate)
Frequently needed BT fields
This selection covers the fields typically needed for a complete invoice. "Required" refers to the respective API object if you send it; for the Invoice object itself, only format, issueDate, invoiceNumber, invoiceTypeCode, invoiceItems and buyer are generally required according to the schema.
| BT number | Meaning | API field | Required |
|---|---|---|---|
| BT-1 | Invoice number | invoiceNumber | Yes |
| BT-2 | Invoice date | issueDate | Yes |
| BT-3 | Invoice type (e.g. 380 = commercial invoice) | invoiceTypeCode | Yes |
| BT-5 | Currency | currency | No |
| BT-9 | Due date | dueDateTime (in specifiedTradePaymentTerms) | No |
| BT-10 | Buyer reference / Leitweg-ID | buyerReference.buyerReferenceId | No |
| BT-13 | Buyer's order reference | buyerReference.IssuerAssignedID | No |
| BT-14 | Reference to the order | orderNumber | No |
| BT-27 | Seller name | seller.name | Yes, within seller |
| BT-31 | Seller VAT ID | seller.vatId | No |
| BT-35 / BT-37 / BT-38 / BT-40 | Seller street, city, postal code, country | seller.street / seller.city / seller.postcode / seller.country | Yes, within seller |
| BT-46 | Customer number at the seller | buyer.id | No |
| BT-47 | Buyer name | buyer.name | Yes, within buyer |
| BT-48 | Buyer VAT ID | buyer.vatId | No |
| BT-50 / BT-52 / BT-53 / BT-55 | Buyer street, city, postal code, country | buyer.street / buyer.city / buyer.postcode / buyer.country | Yes, within buyer |
| BT-72 | Delivery date | deliveryDate | No |
| BT-126 | Line item number | invoiceItems[].id | Yes, within the line item |
| BT-129 | Quantity | invoiceItems[].product.quantity | Yes, within product |
| BT-130 | Unit of measure (e.g. HUR, C62, KGM) | invoiceItems[].product.unitCode | Yes, within product |
| BT-146 | Unit price | invoiceItems[].product.price | Yes, within product |
| BT-153 | Line item description | invoiceItems[].product.name | Yes, within product |
| BT-155 | Item number (assigned by the seller) | invoiceItems[].product.productId | No |
Each invoice line item also needs tax information (taxes) with the tax type, tax category (e.g. S for the standard rate or Z for the zero rate) and tax rate; these three details are required for every line item.
Complete reference
The table above shows a selection of the most frequently needed fields. In total, the API documentation lists considerably more BT fields, including for payment terms, allowances/charges, delivery addresses, contract and project references and globally unique identifiers (GLN/GTIN). You can find the complete, binding list with all field descriptions and examples in the API reference of your faktoora account.
Was this helpful?