Skip to content

Format models

This page explains the meaning of the main fields used in document models (invoices, credit notes) across formats. It helps when filling the web form or building API request bodies. See Formats, Document model and Create documents. For a detailed section-by-section and field-by-field reference with JSON/XML examples, see Invoice model understanding. For full and minimal examples, see Base invoice model example and Minimal invoice model.

Where this applies

  • Web — The unified form (general data, line items, totals, additional) maps each control to one or more model fields.
  • API — Request bodies for upload/model, update/model and the Format API (transform, validate) use the same logical fields. See Create documents and Validate and convert.

Main field groups (by meaning)

Header / document identification

  • Invoice number (ID) — Unique identifier for the invoice (e.g. INV-2024-001). Mandatory in most formats.
  • Issue date — Date the invoice was issued. Usually YYYY-MM-DD.
  • Document type — Invoice or credit note (and subtype if needed, e.g. self-billing). Often a code (e.g. 380 for commercial invoice).
  • Customisation ID / Profile — Format identifier (e.g. Peppol BIS, XRechnung). Usually set by the system from the chosen format.

Parties (seller / buyer)

  • Seller (supplier) — Name, address (street, city, postal code, country), VAT ID, electronic contact. Who issues the invoice.
  • Buyer (customer) — Same structure. Who receives the invoice. For Peppol, the buyer Peppol ID (scheme + value) is required for delivery.
  • Payee / Seller tax representative — Optional; when applicable.

Line items

  • Line ID — Order of the line (integer or string).
  • Quantity / Unit — Quantity (e.g. 10) and unit of measure (e.g. C62 = piece).
  • Description — Text description of the product or service.
  • Unit price / Price — Price per unit (before tax).
  • Line extension amount — Quantity × unit price (net for the line).
  • Tax (per line) — Tax category, rate (%), tax amount. Allowances/charges — Discounts or surcharges per line if applicable.

Totals (document level)

  • Sum of line extensions — Sum of all line net amounts.
  • Allowances / charges (document level) — Discount or surcharge on the whole invoice (amount or percent).
  • Tax subtotals — Per tax category: taxable amount, rate, tax amount.
  • Total tax amount — Sum of all tax.
  • Payable amount (grand total) — Amount due. Prepaid amount — If advance was paid. Amount due — Payable minus prepaid.

Payment and delivery (if applicable)

  • Payment terms — Due date, description (e.g. "Payment within 30 days").
  • Payment means — Bank account (IBAN, BIC), payment reference.
  • Delivery — Delivery date, address (if different from buyer).

Additional (format-dependent)

Other fields may exist in individual formats (notes, buyer reference, contract, project, accounting reference). For exact property names and structure, see the OpenAPI schema (Scalar or Swagger) for the format you use. See API Reference.

!!! tip "Exact field names" Use the interactive API documentation (Scalar or Swagger) to view the request/response schema for your format. Property names and nesting may differ between UBL, CII and the internal model.