Skip to content

Invoice fields

The invoice object accepted by POST /v1/invoices/generate and by the generate_invoice MCP tool. Every field is mapped to an EN 16931 business term (BT) or group (BG); the JSON Schema is served at /v1/schema/invoice.

Conventions: amounts and quantities are decimal strings ("19.90"), percentages too ("20", "5.5"), dates are YYYY-MM-DD, country codes ISO 3166-1 alpha-2. Unknown fields are rejected (422), which catches typos early.

Field Required BT Notes
number yes BT-1 Max 35 chars, letters, digits, . _ / - (BR-FR-01/02)
issue_date yes BT-2
type_code no BT-3 380 invoice (default), 381 credit note, 384 corrected invoice, 386 prepayment, 389 self-billed, 261, 751
currency no BT-5 Default EUR
vat_accounting_currency no BT-6
due_date no BT-9
tax_point_date no BT-7
buyer_reference no BT-10 Often the buyer's service code / routing reference
project_reference, contract_reference, purchase_order_reference, sales_order_reference, receiving_advice_reference, despatch_advice_reference, tender_reference no BT-11..17
buyer_accounting_reference no BT-19
payment_terms no BT-20 Shortcut for payment.terms
operation_type no BT-23 goods, services (default), mixed: derives the French business process code B1/S1/M1
already_paid no BT-23 true gives B2/S2/M2 (invoice already paid at issuance)
business_process no BT-23 Explicit code, overrides the two fields above
french_mentions no BG-1 See below
notes[] no BG-1 {"text": "...", "subject_code": "AAI"}; free-text notes on the document
preceding_invoices[] no BG-3 {"number": "F-2026-0001", "issue_date": "2026-08-01"}, required for credit notes and corrections (BR-FR-06)
additional_documents[] no BG-24 {"id": "PO-7781", "description": "...", "url": "https://..."}
tax_exemption_reason, tax_exemption_reason_code no BT-120 / BT-121 Default text and VATEX code applied to every exempt/reverse-charge line; French defaults are provided per category
prepaid_amount, rounding_amount no BT-113 / BT-114 Applied when totals are computed
totals no BG-22 Send only to override the computed totals (you then own BR-CO-* consistency)

French mentions (french_mentions)

Three notes are mandatory on French B2B invoices (BR-FR-05): late-payment penalties (PMD), the EUR 40 recovery fee (PMT) and the early-payment discount policy (AAB). They are added automatically with standard wording; override any text or disable with {"enabled": false} for non-French sellers:

"french_mentions": {
  "enabled": true,
  "late_payment_penalties": "Pénalités de retard : 3 fois le taux d'intérêt légal.",
  "recovery_fee": "Indemnité forfaitaire pour frais de recouvrement : 40 €.",
  "early_payment_discount": "Pas d'escompte pour paiement anticipé."
}

Parties (seller, buyer)

Field Required BT (seller / buyer) Notes
name yes BT-27 / BT-44 Legal name
trading_name no BT-28 / BT-45
siren FR BT-30 / BT-47 with scheme 0002 9 digits. Mandatory for French parties under the reform (BR-FR-03/04)
siret no BT-29 / BT-46 with scheme 0009 14 digits, must start with the SIREN (BR-FR-08)
legal_registration_id, legal_registration_scheme no BT-30 / BT-47 For non-French companies (e.g. 0208 Belgian enterprise number)
vat_id recommended BT-31 / BT-48 FR40732829320. Required unless the seller is exempt (BR-CO-26)
tax_registration_id no BT-32 Seller only, local tax id when there is no VAT id
legal_info no BT-33 Seller only: legal form, share capital, RCS city; printed on the PDF
electronic_address, electronic_address_scheme no BT-34 / BT-49 Defaults to the SIRET (0225) or the VAT id scheme when omitted
global_ids no BT-29 / BT-46 {"0088": "3012345678901"} GLN and other ISO 6523 ids
address yes BG-5 / BG-8 line1, line2, line3, postal_code, city, country_subdivision, country (required)
contact no BG-6 / BG-9 name, department, phone, email

Delivery (delivery)

name (BT-70), location_id + location_id_scheme (BT-71), address (BG-15), actual_date (BT-72), period_start / period_end (BT-73/74). The French rules require the delivery address when it differs from the buyer's (BR-FR-10).

Payment (payment)

Field BT Notes
means_code BT-81 UNTDID 4461: 30 credit transfer, 58 SEPA transfer, 59 SEPA direct debit, 48 card, 10 cash, 20 cheque, ZZZ other
means_text BT-82
remittance_information BT-83 Defaults to the invoice number
iban, account_name, bic BT-84/85/86 Payee account for transfers
mandate_reference, creditor_reference_id, debited_iban BT-89/90/91 Direct debit
terms BT-20 Payment terms text

Lines (lines[])

Field Required BT Notes
id no BT-126 Auto-numbered 1..n when omitted
item_name yes BT-153
item_description no BT-154 Printed under the item name
note no BT-127
quantity yes BT-129 Decimal string
unit_code no BT-130 UN/ECE Rec 20: C62 unit (default), HUR hour, DAY, MON month, KGM, MTR, LTR, E48 service unit
unit_price yes BT-146 Net unit price, tax excluded
gross_unit_price, price_discount no BT-148 / BT-147 Gross price and item discount
price_base_quantity, price_base_unit_code no BT-149 / BT-150 Price per N units
vat_category no BT-151 S standard (default), Z zero, E exempt, AE reverse charge, K intra-community, G export, O out of scope, L, M
vat_rate for S BT-152 "20", "10", "5.5", "2.1"
seller_item_id, buyer_item_id no BT-155 / BT-156
standard_item_id, standard_item_id_scheme no BT-157 e.g. GTIN with scheme 0160
origin_country no BT-159
attributes no BG-32 {"Couleur": "bleu"}
allowances[], charges[] no BG-27 / BG-28 {"amount": "10.00", "reason": "Remise fidélité", "percentage": "5", "base_amount": "200.00"}
period_start, period_end no BT-134 / BT-135 Service period, printed on the PDF
order_line_reference, buyer_accounting_reference no BT-132 / BT-133
net_amount no BT-131 Computed as quantity x unit_price / price_base_quantity - allowances + charges when omitted

Document-level allowances and charges (allowances[], charges[])

amount (required, tax excluded), base_amount, percentage, reason, reason_code (UNTDID 5189 for allowances, 7161 for charges), vat_category (default S), vat_rate. They enter BT-107/BT-108 and the VAT breakdown.

Totals and VAT breakdown

Computed server-side and returned in the JSON envelope, the X-Facturx-Amount-Due header and the MCP summary:

  • Line total BT-106 = sum of line nets; BT-109 = BT-106 - BT-107 + BT-108.
  • One VAT breakdown row per (category, rate); tax amount rounded per row to 2 decimals (BR-CO-17).
  • BT-112 = BT-109 + BT-110; BT-115 = BT-112 - prepaid + rounding.
  • Exempt categories carry the exemption text and VATEX code (BT-120/121). French defaults: VATEX-FR-FRANCHISE for the VAT franchise (art. 293 B CGI), reverse charge and intra-community wording with the CGI articles.

Common scenarios

{
  "seller": {"name": "Marie Leblanc", "siren": "851234567", "address": {...}},
  "tax_exemption_reason": "TVA non applicable, art. 293 B du CGI",
  "tax_exemption_reason_code": "VATEX-FR-FRANCHISE",
  "lines": [{"item_name": "Création logo", "quantity": "1", "unit_price": "650.00", "vat_category": "E"}]
}

No vat_id on the seller; the API fills BT-32 so BR-CO-26 passes.

{
  "seller": {"name": "Atelier Numérique SAS", "siren": "732829320", "vat_id": "FR40732829320", "address": {...}},
  "buyer": {"name": "Muster GmbH", "vat_id": "DE811907980", "address": {"line1": "...", "city": "Berlin", "postal_code": "10115", "country": "DE"}},
  "lines": [{"item_name": "Consulting", "quantity": "10", "unit_code": "HUR", "unit_price": "120.00", "vat_category": "AE"}]
}

Both VAT ids are required for AE (BR-AE-02). The French wording "Autoliquidation de la TVA par le preneur" is added by default.

{
  "type_code": "381",
  "preceding_invoices": [{"number": "F-2026-0042", "issue_date": "2026-09-01"}],
  "lines": [{"item_name": "Avoir remise commerciale", "quantity": "1", "unit_price": "100.00", "vat_rate": "20"}]
}

Amounts stay positive on a credit note (the type code carries the sign), as required by EN 16931 and the French rules.