> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.
# Document
> Invoice and credit note document structure
## 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
Type of document to create
* `INVOICE` - Standard invoice
* `CREDIT_NOTE` - Credit note (refund/adjustment)
* `DEBIT_NOTE` - Debit note
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`):
Document direction
* `OUTBOUND` - Sending to customer
* `INBOUND` - Received from supplier
## Vendor (Supplier) Information
Your company name
Example: `"Your Company BVBA"`
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"`).
Your company address (full address as single string)
Example: `"Main Street 123, 1000 Brussels, Belgium"`
Department or person at vendor address
Example: `"Accounts Department"`
Your contact email address
Example: `"billing@yourcompany.com"`
## Customer (Buyer) Information
Customer company name
Example: `"Customer Company NV"`
Customer VAT number, including the country prefix. For Belgium this is the VAT number.
Example: `"BE0848934496"`
Customer Peppol participant ID in format `scheme:identifier`
Example: `"0208:0848934496"`
Internal customer reference/ID
Example: `"CUST-12345"`
Customer address (full address as single string)
Example: `"Customer Lane 456, 2000 Antwerp, Belgium"`
Department or person at customer address
Example: `"Accounts Payable"`
Customer contact email
Example: `"ap@customer.com"`
## Invoice Details
Unique invoice number
Example: `"INV-2024-001"`
Invoice issue date in ISO 8601 format (`YYYY-MM-DD`)
Example: `"2024-10-24"`
Payment due date in ISO 8601 format (`YYYY-MM-DD`)
Example: `"2024-11-24"`
Customer purchase order reference. For credit notes, use this to reference the original invoice.
Example: `"PO-12345"` or `"INV-2024-001"` (for credit notes)
Free-text note or description
Example: `"Thank you for your business"` or `"Full refund - goods returned"`
Payment terms description
Example: `"Payment due within 30 days"` or `"Net 30"`
## Financial Fields
Currency code (ISO 4217)
Supported: `EUR`, `USD`, `GBP`, `JPY`, `CHF`, `CAD`, `AUD`, `NZD`, `CNY`, `INR`, `SEK`, `NOK`, `DKK`, `SGD`, `HKD`
Example: `"EUR"`
Taxable base amount (after document-level allowances and charges, before tax)
Corresponds to UBL `cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount`
Example: `1000.00`
Total document-level allowances (discounts only, not charges)
Corresponds to UBL `cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount`
Example: `50.00`
Total VAT/tax amount
Corresponds to UBL `cac:TaxTotal/cbc:TaxAmount`
Example: `210.00`
Total invoice amount including tax (subtotal + total\_tax)
Corresponds to UBL `cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount`
Example: `1210.00`
Amount due for payment after prepayments
Corresponds to UBL `cac:LegalMonetaryTotal/cbc:PayableAmount`
Example: `1210.00`
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
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
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
VAT exemption explanation
Example: `"Reverse charge applies - Art. 196 EU VAT Directive"`
## Service Period
Service period start date (ISO 8601: `YYYY-MM-DD`)
Example: `"2024-10-01"`
Service period end date (ISO 8601: `YYYY-MM-DD`)
Example: `"2024-10-31"`
## Additional Addresses
Billing address (if different from customer address)
Example: `"Billing Street 1, 1000 Brussels, Belgium"`
Recipient at billing address
Example: `"Accounts Payable Department"`
Delivery/shipping address
Example: `"Warehouse 5, Industrial Park, 3000 Leuven, Belgium"`
Recipient at shipping address
Example: `"Warehouse Manager"`
Service location address
Example: `"Service Location 3, 3000 Leuven, Belgium"`
Recipient at service address
Remittance/payment address
Example: `"Payment Processing Center, 1000 Brussels, Belgium"`
Recipient at remittance address
## Line Items
Array of line items (minimum 1 required)
See [LineItem schema](/api-reference/schemas/line-item) for details.
Example:
```json theme={null}
[
{
"description": "Professional Services",
"quantity": 10,
"unit": "C62",
"unit_price": 100.00,
"tax_rate": "21.00"
}
]
```
## Payment Details
Array of payment method details
Example:
```json theme={null}
[
{
"iban": "BE68539007547034",
"swift": "GEBABEBB",
"payment_reference": "INV-2024-001"
}
]
```
## Allowances and Charges
Document-level allowances (discounts)
Example:
```json theme={null}
[
{
"amount": 50.00,
"reason": "Early payment discount (5%)",
"tax_code": "S",
"tax_rate": "21.00"
}
]
```
Document-level charges (fees)
Example:
```json theme={null}
[
{
"amount": 25.00,
"reason": "Shipping and handling",
"tax_code": "S",
"tax_rate": "21.00"
}
]
```
## Tax Details
Detailed tax breakdown by category/rate
Automatically calculated if not provided.
## Attachments
Document attachments (supporting files)
Example:
```json theme={null}
[
{
"file_name": "supporting_document.pdf",
"file_type": "application/pdf",
"file_data": ""
}
]
```
## Example
Complete invoice example:
```json theme={null}
{
"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"
}
]
}
```
## Related
* [LineItem Schema](/api-reference/schemas/line-item)
* [Creating Invoices Guide](/guides/creating-invoices)
* [Validation Guide](/guides/validation)