Creating E-Invoices

Overview

The e-invoice.be API allows you to create invoices and credit notes that comply with the European e-invoicing standard (EN 16931) and transmit them via the Peppol network.

Before You Start

Enable test mode for development and testing. When test mode is enabled, documents are emailed instead of being sent via Peppol, allowing you to safely test your integration. Contact [email protected] to enable test mode. Learn more about test mode →

Workflow

Creating and sending an e-invoice involves these steps:

Validate your JSON invoice data (required during development)
Create the document - only valid invoices can be created
Send the document via Peppol (or email if test mode is enabled)

You must validate your invoice JSON before creating a document. The API only accepts invoices that can be converted into valid UBL BIS Billing 3.0 format. Use /api/validate/json during development to test your payload.

Step 1: Validate Your Invoice Data (Required)

Before creating an invoice, validate your JSON payload using POST /api/validate/json.

curl -X POST "https://api.e-invoice.be/api/validate/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "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": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, Belgium",
  "vendor_email": "[email protected]",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumainplein 6 bus 5, 1040 Brussel, Belgium",
  "items": [
    {
      "description": "Professional Services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "payment_term": "Payment due within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2024-001"
    }
  ]
}'

Validation Response

Success - Ready to create:

{
  "valid": true,
  "message": "Invoice JSON is valid and can be converted to UBL BIS Billing 3.0"
}

Validation errors:

{
  "valid": false,
  "errors": [
    {
      "field": "vendor_tax_id",
      "message": "Invalid tax ID format. Expected format: country code + number (e.g., BE1018265814 for Belgium)"
    },
    {
      "field": "items[0].tax_rate",
      "message": "Invalid tax rate format. Must be a percentage string (e.g., '21.00')"
    }
  ]
}

Use /api/validate/json extensively during development. This endpoint does not create any documents - it only validates that your JSON can be converted to valid UBL format. See the Validation Guide for more details.

Step 2: Create the Invoice

Once validation passes, use the exact same JSON payload with POST /api/documents/.

curl -X POST "https://api.e-invoice.be/api/documents/" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
  "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": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, Belgium",
  "vendor_email": "[email protected]",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumainplein 6 bus 5, 1040 Brussel, Belgium",
  "items": [
    {
      "description": "Professional Services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "payment_term": "Payment due within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2024-001"
    }
  ]
}'

Response

{
  "id": "doc_abc123",
  "document_type": "INVOICE",
  "state": "DRAFT",
  "invoice_id": "INV-2024-001",
  "invoice_date": "2024-10-24",
  "invoice_total": 1210.00,
  "total_tax": 210.00,
  "created_at": 1729468923,
  "updated_at": 1729468923
}

Understanding the Invoice Structure

Required Fields

Only the items array is strictly required. All other fields are optional but recommended for complete invoices:

Field	Description	Required
`items`	Array of invoice line items	Yes (min 1)
`document_type`	Document type: `INVOICE`, `CREDIT_NOTE`, or `DEBIT_NOTE`	No (default: INVOICE)
`invoice_id`	Your unique invoice number	Recommended
`invoice_date`	Invoice date (ISO 8601: `YYYY-MM-DD`)	Recommended
`currency`	Currency code (e.g., `EUR`, `USD`, `GBP`)	No (default: EUR)

Vendor (Supplier) Fields

Information about your company (the seller):

Field	Description	Example
`vendor_name`	Your company name	`"E-INVOICE BV"`
`vendor_tax_id`	Your VAT/Tax ID	`"BE1018265814"`
`vendor_address`	Your full address	`"Brusselsesteenweg 119/A, 1980 Zemst, Belgium"`
`vendor_email`	Your contact email	`"[email protected]"`

The vendor_tax_id is your company’s VAT or tax identification number (not the Peppol ID).

For Belgian companies: Use the full VAT number including ‘BE’ prefix (e.g., BE1018265814)
The API will automatically convert this to the appropriate Peppol ID format when transmitting via Peppol

Customer Fields

Information about your customer (the buyer):

Field	Description	Example
`customer_name`	Customer company name	`"OpenPeppol VZW"`
`customer_tax_id`	Customer VAT/Tax ID	`"BE0848934496"`
`customer_address`	Customer full address	`"Robert Schumainplein 6 bus 5, 1040 Brussel, Belgium"`
`customer_email`	Customer contact email	`"[email protected]"`

Line Items

Each line item in the items array represents a product or service:

{
  "description": "Product/Service description",  // What is being sold
  "quantity": 10,                                 // Quantity
  "unit": "C62",                                  // Unit of measure (C62 = pieces/units)
  "unit_price": 100.00,                          // Price per unit (excluding VAT)
  "amount": 1000.00,                             // Line total (quantity × unit_price)
  "tax_rate": "21.00"                            // VAT percentage as string
}

Required item fields:

At least description or unit_price should be provided for meaningful invoices

Common unit codes:

C62 - Units/pieces
HUR - Hours
DAY - Days
MTR - Meters
KGM - Kilograms

Tax rate format:

Must be a string representing a percentage
Examples: "21.00", "6.00", "0.00"
Standard Belgian VAT rates: "21.00" (standard), "6.00" (reduced), "0.00" (zero-rated)

Optional Fields

Payment Details

{
  "payment_term": "Net 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2024-001"
    }
  ]
}

Additional Addresses

{
  "billing_address": "Billing Street 1, 1000 Brussels, Belgium",
  "billing_address_recipient": "Accounts Payable Department",
  "shipping_address": "Delivery Street 2, 2000 Antwerp, Belgium",
  "shipping_address_recipient": "Warehouse Manager",
  "service_address": "Service Location 3, 3000 Leuven, Belgium"
}

Allowances & Charges

{
  "allowances": [
    {
      "amount": 50.00,
      "reason": "Early payment discount",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ],
  "charges": [
    {
      "amount": 25.00,
      "reason": "Shipping costs",
      "tax_code": "S",
      "tax_rate": "21.00"
    }
  ]
}

See the Advanced Invoicing Guide for more details.

References and Notes

{
  "purchase_order": "PO-12345",
  "note": "Thank you for your business"
}

Step 3: Send the Document

Once your invoice is created, send it to the recipient using POST /api/documents/{document_id}/send.

curl -X POST "https://api.e-invoice.be/api/documents/doc_abc123/send" \
     -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "doc_abc123",
  "state": "TRANSIT",
  "message": "Document queued for transmission"
}

Peppol ID Routing

By default, the sender and receiver Peppol IDs are automatically derived from the company identifiers in your document:

Derived from vendor_tax_id / customer_tax_id (VAT/tax number) OR vendor_id / customer_id (company registration number)
For Belgian companies: Tax ID BE1018265814 → Peppol ID 0208:1018265814
The 0208 scheme is mandatory for Belgian companies (required by Belgian government)
This automatic conversion happens regardless of any endpoint IDs in UBL documents

Belgian Peppol Requirement: All Belgian companies must use the 0208 scheme with their enterprise number (CBE). This is automatically handled when you provide a Belgian tax ID starting with BE.

Explicitly Specifying Peppol IDs (Recommended)

Best Practice: Always explicitly specify sender and receiver Peppol IDs using query parameters to ensure documents are routed to the correct endpoints. While automatic derivation works in most cases, explicit routing prevents delivery failures and ensures full control over transmission.

To send to a specific Peppol endpoint, explicitly set the Peppol IDs using query parameters:

curl -X POST "https://api.e-invoice.be/api/documents/doc_abc123/send?sender_peppol_scheme=0208&sender_peppol_id=1018265814&receiver_peppol_scheme=0208&receiver_peppol_id=0848934496" \
     -H "Authorization: Bearer YOUR_API_KEY"

Available query parameters:

Parameter	Description	Example
`sender_peppol_scheme`	Sender’s Peppol scheme ID	`0208`
`sender_peppol_id`	Sender’s Peppol identifier	`1018265814`
`receiver_peppol_scheme`	Receiver’s Peppol scheme ID	`0088`
`receiver_peppol_id`	Receiver’s Peppol identifier	`1234567890123`

Common Peppol schemes:

0208 - Belgian enterprise number (BE)
0088 - Global Location Number (GLN)
0106 - Dutch KVK

Always verify the recipient is registered at the specified Peppol endpoint before sending. Use /api/validate/peppol-id?peppol_id=scheme:identifier to confirm registration and prevent delivery failures.

What Happens Next?

The behavior depends on whether test mode is enabled: Test mode disabled (production):

Document is transmitted via the Peppol network
Recipient receives it in their official e-invoicing system
Delivery confirmed via Access Point acknowledgments

Test mode enabled (testing):

Document is converted to UBL XML
UBL XML is sent via email to the address configured for your account
No actual Peppol transmission occurs
Perfect for testing without affecting real recipients

Test mode is a setting on your account. Contact [email protected] to enable test mode for development or disable it when you’re ready to go live.

Document States

State	Description
`DRAFT`	Created but not sent
`TRANSIT`	Being transmitted (Peppol or email)
`SENT`	Successfully delivered to recipient
`FAILED`	Transmission failed
`RECEIVED`	Received from another party

Automatic Retries: Documents in TRANSIT use an exponential backoff 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). This maximizes delivery success during temporary network issues.Manual Retry: If a document reaches FAILED state, you can retry delivery by calling POST /api/documents/{document_id}/send again, which will transition it back to TRANSIT for another delivery attempt.Track delivery status using webhooks or by polling GET /api/documents/{document_id}Coming soon: Detailed transmission attempt history will be available in a future release, showing all retry attempts with timestamps and failure reasons.

Complete Example

Here’s a complete Node.js example:

const axios = require('axios');

// Most users should use the production API
const BASE_URL = 'https://api.e-invoice.be';

const api = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${process.env.E_INVOICE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

async function createAndSendInvoice() {
  const invoiceData = {
    document_type: 'INVOICE',
    invoice_id: 'INV-2024-001',
    invoice_date: '2024-10-24',
    due_date: '2024-11-24',
    currency: 'EUR',
    vendor_name: 'E-INVOICE BV',
    vendor_tax_id: 'BE1018265814',
    vendor_address: 'Brusselsesteenweg 119/A, 1980 Zemst, Belgium',
    vendor_email: '[email protected]',
    customer_name: 'OpenPeppol VZW',
    customer_tax_id: 'BE0848934496',
    customer_address: 'Robert Schumainplein 6 bus 5, 1040 Brussel, Belgium',
    items: [
      {
        description: 'Professional Services',
        quantity: 10,
        unit: 'C62',
        unit_price: 100.00,
        amount: 1000.00,
        tax_rate: '21.00'
      }
    ],
    payment_term: 'Net 30 days',
    payment_details: [
      {
        iban: 'BE68539007547034',
        swift: 'GEBABEBB',
        payment_reference: 'INV-2024-001'
      }
    ]
  };

  try {
    // 1. Validate JSON (always do this during development)
    const validation = await api.post('/api/validate/json', invoiceData);

    if (!validation.data.valid) {
      console.error('Validation failed:', validation.data.errors);
      return;
    }

    console.log('✓ Invoice JSON is valid');

    // 2. Create invoice (uses same payload)
    const invoice = await api.post('/api/documents/', invoiceData);
    console.log('✓ Invoice created:', invoice.data.id);

    // 3. Send (via email if test mode enabled, Peppol if disabled)
    const result = await api.post(`/api/documents/${invoice.data.id}/send`);
    console.log('✓ Invoice sent:', result.data.state);

  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

createAndSendInvoice();

If test mode is enabled on your account, this will email the UBL XML. If test mode is disabled, it will send via Peppol. Your code doesn’t need to change - just the test mode setting on your account.

Working with Credit Notes

Credit notes follow the same structure, but set document_type: "CREDIT_NOTE":

{
  "document_type": "CREDIT_NOTE",
  "invoice_id": "CN-2024-001",
  "billing_reference": "INV-2024-001",  // Original invoice reference
  "invoice_date": "2024-10-24",
  "currency": "EUR",
  "vendor_name": "Your Company",
  "vendor_tax_id": "BE1018265814",
  "customer_name": "Customer Company",
  "customer_tax_id": "BE0848934496",
  "items": [ ... ]
  // ... rest of the structure same as invoices
}

Next Steps

Validation Guide

Test invoices during development

Lookup Participants

Find customer Peppol IDs

Set Up Webhooks

Get delivery notifications

API Reference

Explore all endpoints

Getting started

Core guides

Alternative formats

Integration

Partners

Overview

Before You Start

Workflow

Step 1: Validate Your Invoice Data (Required)

Validation Response

Step 2: Create the Invoice

Response

Understanding the Invoice Structure

Required Fields

Vendor (Supplier) Fields

Customer Fields

Line Items

Optional Fields

Step 3: Send the Document

Response

Peppol ID Routing

Explicitly Specifying Peppol IDs (Recommended)

What Happens Next?

Document States

Complete Example

Working with Credit Notes

Next Steps

Validation Guide

Lookup Participants

Set Up Webhooks

API Reference

Getting started

Core guides

Alternative formats

Integration

Partners

​Overview

​Before You Start

​Workflow

​Step 1: Validate Your Invoice Data (Required)

​Validation Response

​Step 2: Create the Invoice

​Response

​Understanding the Invoice Structure

​Required Fields

​Vendor (Supplier) Fields

​Customer Fields

​Line Items

​Optional Fields

​Step 3: Send the Document

​Response

​Peppol ID Routing

​Explicitly Specifying Peppol IDs (Recommended)

​What Happens Next?

​Document States

​Complete Example

​Working with Credit Notes

​Next Steps

Validation Guide

Lookup Participants

Set Up Webhooks

API Reference

Overview

Before You Start

Workflow

Step 1: Validate Your Invoice Data (Required)

Validation Response

Step 2: Create the Invoice

Response

Understanding the Invoice Structure

Required Fields

Vendor (Supplier) Fields

Customer Fields

Line Items

Optional Fields

Step 3: Send the Document

Response

Peppol ID Routing

Explicitly Specifying Peppol IDs (Recommended)

What Happens Next?

Document States

Complete Example

Working with Credit Notes

Next Steps