Document

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

enum

default:"INVOICE"

Type of document to create

INVOICE - Standard invoice
CREDIT_NOTE - Credit note (refund/adjustment)
DEBIT_NOTE - Debit note

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):

Documents in TRANSIT state use an exponential backoff retry strategy with 10 retry attempts before transitioning to FAILED. Retry delays are: 1, 2, 4, 8, 16, 32, 64, 128, 256, and 360 minutes (final retry capped at 6 hours).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):

enum

default:"OUTBOUND"

Document direction

OUTBOUND - Sending to customer
INBOUND - Received from supplier

Vendor (Supplier) Information

string

Your company nameExample: "Your Company BVBA"

string

Your VAT number, including the country prefix. For Belgium this is the VAT number.Example: "BE1018265814"The API automatically derives the Peppol participant ID from this value when transmitting. To set the recipient’s Peppol ID explicitly, use customer_peppol_id (format scheme:identifier, e.g. "0208:0123456789").

string

Your company address (full address as single string)Example: "Main Street 123, 1000 Brussels, Belgium"

string

Department or person at vendor addressExample: "Accounts Department"

string

Your contact email addressExample: "billing@yourcompany.com"

Customer (Buyer) Information

string

Customer company nameExample: "Customer Company NV"

string

Customer VAT number, including the country prefix. For Belgium this is the VAT number.Example: "BE0848934496"

string

Customer Peppol participant ID in format scheme:identifierExample: "0208:0848934496"

string

Internal customer reference/IDExample: "CUST-12345"

string

Customer address (full address as single string)Example: "Customer Lane 456, 2000 Antwerp, Belgium"

string

Department or person at customer addressExample: "Accounts Payable"

string

Customer contact emailExample: "ap@customer.com"

Invoice Details

string

Unique invoice numberExample: "INV-2024-001"

string

Invoice issue date in ISO 8601 format (YYYY-MM-DD)Example: "2024-10-24"

string

Payment due date in ISO 8601 format (YYYY-MM-DD)Example: "2024-11-24"

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)

string

Free-text note or descriptionExample: "Thank you for your business" or "Full refund - goods returned"

string

Payment terms descriptionExample: "Payment due within 30 days" or "Net 30"

Financial Fields

enum

default:"EUR"

Currency code (ISO 4217)Supported: EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, SEK, NOK, DKK, SGD, HKDExample: "EUR"

number

Taxable base amount (after document-level allowances and charges, before tax)Corresponds to UBL cac:LegalMonetaryTotal/cbc:TaxExclusiveAmountExample: 1000.00

number

Total document-level allowances (discounts only, not charges)Corresponds to UBL cac:LegalMonetaryTotal/cbc:AllowanceTotalAmountExample: 50.00

number

Total VAT/tax amountCorresponds to UBL cac:TaxTotal/cbc:TaxAmountExample: 210.00

number

Total invoice amount including tax (subtotal + total_tax)Corresponds to UBL cac:LegalMonetaryTotal/cbc:TaxInclusiveAmountExample: 1210.00

number

Amount due for payment after prepaymentsCorresponds to UBL cac:LegalMonetaryTotal/cbc:PayableAmountExample: 1210.00

number

Previous outstanding balance (if any). Hidden/internal field: it is excluded from the transmitted document and does not appear in the generated UBL.Example: 100.00

Tax Information

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

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

string

VAT exemption explanationExample: "Reverse charge applies - Art. 196 EU VAT Directive"

Service Period

string

Service period start date (ISO 8601: YYYY-MM-DD)Example: "2024-10-01"

string

Service period end date (ISO 8601: YYYY-MM-DD)Example: "2024-10-31"

Additional Addresses

string

Billing address (if different from customer address)Example: "Billing Street 1, 1000 Brussels, Belgium"

string

Recipient at billing addressExample: "Accounts Payable Department"

string

Delivery/shipping addressExample: "Warehouse 5, Industrial Park, 3000 Leuven, Belgium"

string

Recipient at shipping addressExample: "Warehouse Manager"

string

Service location addressExample: "Service Location 3, 3000 Leuven, Belgium"

string

Recipient at service address

string

Remittance/payment addressExample: "Payment Processing Center, 1000 Brussels, Belgium"

string

Recipient at remittance address

Line 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

array

Array of payment method detailsExample:

[
  {
    "iban": "BE68539007547034",
    "swift": "GEBABEBB",
    "payment_reference": "INV-2024-001"
  }
]

Allowances and Charges

array

Document-level allowances (discounts)Example:

[
  {
    "amount": 50.00,
    "reason": "Early payment discount (5%)",
    "tax_code": "S",
    "tax_rate": "21.00"
  }
]

array

Document-level charges (fees)Example:

[
  {
    "amount": 25.00,
    "reason": "Shipping and handling",
    "tax_code": "S",
    "tax_rate": "21.00"
  }
]

Tax Details

array

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

Attachments

array

Document attachments (supporting files)Example:

[
  {
    "file_name": "supporting_document.pdf",
    "file_type": "application/pdf",
    "file_data": "<base64-encoded file data>"
  }
]

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": "BE1018265814",
  "vendor_address": "Main Street 123, 1000 Brussels, Belgium",
  "vendor_email": "billing@yourcompany.com",
  "customer_name": "Customer Company NV",
  "customer_tax_id": "BE0848934496",
  "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"
    }
  ]
}

Documents

Inbox

Mailbox

Outbox

Drafts

Validate

Lookup

Tenant

Webhooks

Conversion

Overview

Document Metadata

Vendor (Supplier) Information

Customer (Buyer) Information

Invoice Details

Financial Fields

Tax Information

Service Period

Additional Addresses

Line Items

Payment Details

Allowances and Charges

Tax Details

Attachments

Example

​Overview

​Document Metadata

​Vendor (Supplier) Information

​Customer (Buyer) Information

​Invoice Details

​Financial Fields

​Tax Information

​Service Period

​Additional Addresses

​Line Items

​Payment Details

​Allowances and Charges

​Tax Details

​Attachments

​Example

​Related

Overview

Document Metadata

Vendor (Supplier) Information

Customer (Buyer) Information

Invoice Details

Financial Fields

Tax Information

Service Period

Additional Addresses

Line Items

Payment Details

Allowances and Charges

Tax Details

Attachments

Example

Related