Skip to main content

​
Overview

The Document schema defines the structure for creating invoices, credit notes, and debit notes via the e-invoice.be API. This is the primary schema used when calling POST /api/documents/.
Only the items array is strictly required. All other fields are optional but recommended for complete, Peppol-compliant e-invoices.

​
Document Metadata

​
document_type
enum
default:"INVOICE"
Type of document to create
  • INVOICE - Standard invoice
  • CREDIT_NOTE - Credit note (refund/adjustment)
  • DEBIT_NOTE - Debit note
​
state
enum
default:"DRAFT"
Document state
  • DRAFT - Created but not sent
  • TRANSIT - Being transmitted
  • SENT - Successfully delivered
  • FAILED - Transmission failed
  • RECEIVED - Received from another party
State Flow Diagrams:Outbound documents (direction: OUTBOUND):Outbound document state flow
Documents in TRANSIT state use an exponential backoff retry strategy over 24 hours before transitioning to FAILED.Documents in FAILED state can be retried by calling POST /api/documents/{id}/send again, which will transition them back to TRANSIT for another delivery attempt.Coming soon: Detailed transmission attempt history will be available in a future release, allowing you to view all retry attempts, timestamps, and failure reasons for each transmission.
Inbound documents (direction: INBOUND):Inbound document state flow
​
direction
enum
default:"OUTBOUND"
Document direction
  • OUTBOUND - Sending to customer
  • INBOUND - Received from supplier

​
Vendor (Supplier) Information

​
vendor_name
string
Your company nameExample: "Your Company BVBA"
​
vendor_tax_id
string
Your Peppol participant ID in format scheme:identifierExample: "0208:0123456789" (Belgian CBE number)See Peppol ID schemes
​
vendor_address
string
Your company address (full address as single string)Example: "Main Street 123, 1000 Brussels, Belgium"
​
vendor_address_recipient
string
Department or person at vendor addressExample: "Accounts Department"
​
vendor_email
string
Your contact email addressExample: "[email protected]"

​
Customer (Buyer) Information

​
customer_name
string
Customer company nameExample: "Customer Company NV"
​
customer_tax_id
string
Customer Peppol participant ID in format scheme:identifierExample: "0208:0987654321"
​
customer_id
string
Internal customer reference/IDExample: "CUST-12345"
​
customer_address
string
Customer address (full address as single string)Example: "Customer Lane 456, 2000 Antwerp, Belgium"
​
customer_address_recipient
string
Department or person at customer addressExample: "Accounts Payable"
​
customer_email
string
Customer contact emailExample: "[email protected]"

​
Invoice Details

​
invoice_id
string
Unique invoice numberExample: "INV-2024-001"
​
invoice_date
string
Invoice issue date in ISO 8601 format (YYYY-MM-DD)Example: "2024-10-24"
​
due_date
string
Payment due date in ISO 8601 format (YYYY-MM-DD)Example: "2024-11-24"
​
purchase_order
string
Customer purchase order reference. For credit notes, use this to reference the original invoice.Example: "PO-12345" or "INV-2024-001" (for credit notes)
​
note
string
Free-text note or descriptionExample: "Thank you for your business" or "Full refund - goods returned"
​
payment_term
string
Payment terms descriptionExample: "Payment due within 30 days" or "Net 30"

​
Financial Fields

​
currency
enum
default:"EUR"
Currency code (ISO 4217)Supported: EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, SEK, NOK, DKK, SGD, HKDExample: "EUR"
​
subtotal
number
Taxable base amount (after document-level allowances and charges, before tax)Corresponds to UBL cac:LegalMonetaryTotal/cbc:TaxExclusiveAmountExample: 1000.00
​
total_discount
number
Total document-level allowances (discounts only, not charges)Corresponds to UBL cac:LegalMonetaryTotal/cbc:AllowanceTotalAmountExample: 50.00
​
total_tax
number
Total VAT/tax amountCorresponds to UBL cac:TaxTotal/cbc:TaxAmountExample: 210.00
​
invoice_total
number
Total invoice amount including tax (subtotal + total_tax)Corresponds to UBL cac:LegalMonetaryTotal/cbc:TaxInclusiveAmountExample: 1210.00
​
amount_due
number
Amount due for payment after prepaymentsCorresponds to UBL cac:LegalMonetaryTotal/cbc:PayableAmountExample: 1210.00
​
previous_unpaid_balance
number
Previous outstanding balance (if any)Example: 100.00

​
Tax Information

​
tax_code
enum
default:"S"
Tax category code (UNCL5305)
  • S - Standard rate (most common)
  • Z - Zero rated
  • E - Exempt from tax
  • AE - VAT Reverse Charge
  • K, G, O, L, M, B - Other special cases
​
vatex
enum
VAT exemption reason code (when tax_code is E, AE, K, G, O, L, M, or B)Example: "VATEX-EU-132" for intra-community supply
​
vatex_note
string
VAT exemption explanationExample: "Reverse charge applies - Art. 196 EU VAT Directive"

​
Service Period

​
service_start_date
string
Service period start date (ISO 8601: YYYY-MM-DD)Example: "2024-10-01"
​
service_end_date
string
Service period end date (ISO 8601: YYYY-MM-DD)Example: "2024-10-31"

​
Additional Addresses

​
billing_address
string
Billing address (if different from customer address)Example: "Billing Street 1, 1000 Brussels, Belgium"
​
billing_address_recipient
string
Recipient at billing addressExample: "Accounts Payable Department"
​
shipping_address
string
Delivery/shipping addressExample: "Warehouse 5, Industrial Park, 3000 Leuven, Belgium"
​
shipping_address_recipient
string
Recipient at shipping addressExample: "Warehouse Manager"
​
service_address
string
Service location addressExample: "Service Location 3, 3000 Leuven, Belgium"
​
service_address_recipient
string
Recipient at service address
​
remittance_address
string
Remittance/payment addressExample: "Payment Processing Center, 1000 Brussels, Belgium"
​
remittance_address_recipient
string
Recipient at remittance address

​
Line Items

​
items
array
required
Array of line items (minimum 1 required)See LineItem schema for details.Example:
[
  {
    "description": "Professional Services",
    "quantity": 10,
    "unit": "C62",
    "unit_price": 100.00,
    "tax_rate": "21.00"
  }
]

​
Payment Details

​
payment_details
array
Array of payment method detailsExample:
[
  {
    "iban": "BE68539007547034",
    "swift": "GEBABEBB",
    "payment_reference": "INV-2024-001"
  }
]

​
Allowances and Charges

​
allowances
array
Document-level allowances (discounts)Example:
[
  {
    "amount": 50.00,
    "reason": "Early payment discount (5%)",
    "tax_code": "S",
    "tax_rate": "21.00"
  }
]
​
charges
array
Document-level charges (fees)Example:
[
  {
    "amount": 25.00,
    "reason": "Shipping and handling",
    "tax_code": "S",
    "tax_rate": "21.00"
  }
]

​
Tax Details

​
tax_details
array
Detailed tax breakdown by category/rateAutomatically calculated if not provided.

​
Attachments

​
attachments
array
Document attachments (supporting files)Example:
[
  {
    "filename": "supporting_document.pdf",
    "description": "Supporting documentation"
  }
]

​
Example

Complete invoice example: 
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2024-001",
  "invoice_date": "2024-10-24",
  "due_date": "2024-11-24",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "Your Company BVBA",
  "vendor_tax_id": "0208:0123456789",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "vendor_email": "[email protected]",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "0208:0987654321",
  "customer_address": "Customer Lane 456, 2000 Antwerp, Belgium",
  "items": [
    {
      "description": "Professional Services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "tax_rate": "21.00"
    }
  ],
  "payment_term": "Net 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2024-001"
    }
  ]
}