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"
}

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 multiple retry attempts over 24 hours before transitioning to FAILED. This maximizes delivery success during temporary network issues.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

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

​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

What Happens Next?

Document States

Complete Example

Working with Credit Notes

Next Steps