Create e-invoices

Overview

With the e-invoice.be API you create an invoice from JSON. The API converts the JSON to UBL that complies with the European e-invoicing standard (EN 16931) and transmits the document on the Peppol network.

Before you start

Develop and test with a sandbox company. A sandbox company runs in test mode: the API sends each document as UBL XML to the contact email address of the company, and nothing goes to the Peppol network. The API host and the endpoints are the same as for a production company. See Test mode and sandbox companies.

You need the API key of the company. See Authentication.

Workflow

To send an e-invoice, do these steps:

Validate the JSON invoice data while you develop.
Create the document. The API accepts only an invoice that it can convert to valid UBL BIS Billing 3.0.
Send the document. A production company sends on the Peppol network. A sandbox company sends an email.

Validation is not a separate mandatory call. POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.

Validate the invoice data

The examples on this page use this payload:

Invoice

{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}

Replace the vendor fields with the data of your company. The API rejects a document if the Peppol ID of the vendor is not one of the peppol_ids of your company. POST /api/validate/json does not create a document and does not check the vendor. Thus you can validate the example without changes.

curl -X POST "https://api.e-invoice.be/api/validate/json" \
  -H "Authorization: Bearer $E_INVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}'

const invoice = {
  document_type: "INVOICE",
  invoice_id: "INV-2026-001",
  invoice_date: "2026-10-01",
  due_date: "2026-10-31",
  currency: "EUR",
  purchase_order: "PO-12345",
  vendor_name: "E-INVOICE BV",
  vendor_tax_id: "BE1018265814",
  vendor_address: "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  vendor_email: "billing@e-invoice.be",
  customer_name: "OpenPeppol VZW",
  customer_tax_id: "BE0848934496",
  customer_address: "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  items: [
    {
      description: "Professional services",
      quantity: 10,
      unit: "C62",
      unit_price: 100.00,
      amount: 1000.00,
      tax_rate: "21.00"
    }
  ],
  subtotal: 1000.00,
  total_tax: 210.00,
  invoice_total: 1210.00,
  amount_due: 1210.00,
  payment_term: "Payment within 30 days",
  payment_details: [
    {
      iban: "BE68539007547034",
      swift: "GEBABEBB",
      payment_reference: "INV-2026-001"
    }
  ]
};

const response = await fetch("https://api.e-invoice.be/api/validate/json", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(invoice),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result);

import os

import requests

invoice = {
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}

response = requests.post(
    "https://api.e-invoice.be/api/validate/json",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    json=invoice,
    timeout=30,
)
if not response.ok:
    raise SystemExit(f"HTTP {response.status_code}: {response.text}")
print(response.json())

<?php
$invoice = [
  "document_type" => "INVOICE",
  "invoice_id" => "INV-2026-001",
  "invoice_date" => "2026-10-01",
  "due_date" => "2026-10-31",
  "currency" => "EUR",
  "purchase_order" => "PO-12345",
  "vendor_name" => "E-INVOICE BV",
  "vendor_tax_id" => "BE1018265814",
  "vendor_address" => "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email" => "billing@e-invoice.be",
  "customer_name" => "OpenPeppol VZW",
  "customer_tax_id" => "BE0848934496",
  "customer_address" => "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items" => [
    [
      "description" => "Professional services",
      "quantity" => 10,
      "unit" => "C62",
      "unit_price" => 100.00,
      "amount" => 1000.00,
      "tax_rate" => "21.00"
    ]
  ],
  "subtotal" => 1000.00,
  "total_tax" => 210.00,
  "invoice_total" => 1210.00,
  "amount_due" => 1210.00,
  "payment_term" => "Payment within 30 days",
  "payment_details" => [
    [
      "iban" => "BE68539007547034",
      "swift" => "GEBABEBB",
      "payment_reference" => "INV-2026-001"
    ]
  ]
];

$ch = curl_init("https://api.e-invoice.be/api/validate/json");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("E_INVOICE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($invoice),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $body");
}
print_r(json_decode($body, true));

using System.Net.Http.Headers;
using System.Text;

var invoice = """
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}
""";

using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var response = await client.PostAsync(
    "/api/validate/json",
    new StringContent(invoice, Encoding.UTF8, "application/json"));

var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {body}");
}
Console.WriteLine(body);

A valid payload gives is_valid: true, an empty issues list and the generated UBL in ubl_document. The UBL is shortened here.

Valid

{
  "id": "b55354b0-5c69-489b-a8f7-44be7d5bdd6b",
  "file_name": "b55354b0-5c69-489b-a8f7-44be7d5bdd6b.xml",
  "is_valid": true,
  "issues": [],
  "ubl_document": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\"> (shortened) </Invoice>"
}

A payload that breaks a rule gives is_valid: false. Each entry in issues has a message, a type (error or warning) and the name of the rule set in schematron. The fields rule_id, flag, location and test are optional.

Not valid

{
  "id": "b55354b0-5c69-489b-a8f7-44be7d5bdd6b",
  "file_name": "b55354b0-5c69-489b-a8f7-44be7d5bdd6b.xml",
  "is_valid": false,
  "issues": [
    {
      "message": "Belgian enterprise number MUST be stated in the correct format.",
      "type": "error",
      "rule_id": "PEPPOL-COMMON-R043",
      "flag": "fatal",
      "schematron": "PEPPOL-EN16931-UBL"
    }
  ]
}

See the validation guide for the rules and the corrections. For all status codes and error formats, see Errors and troubleshooting.

Create the invoice

Send the same JSON payload to POST /api/documents/. Replace the vendor fields with the data of your company before you run this example: the API returns 406 if the Peppol ID of the vendor is not one of the peppol_ids of your company.

curl -X POST "https://api.e-invoice.be/api/documents/" \
  -H "Authorization: Bearer $E_INVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}'

const invoice = {
  document_type: "INVOICE",
  invoice_id: "INV-2026-001",
  invoice_date: "2026-10-01",
  due_date: "2026-10-31",
  currency: "EUR",
  purchase_order: "PO-12345",
  vendor_name: "E-INVOICE BV",
  vendor_tax_id: "BE1018265814",
  vendor_address: "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  vendor_email: "billing@e-invoice.be",
  customer_name: "OpenPeppol VZW",
  customer_tax_id: "BE0848934496",
  customer_address: "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  items: [
    {
      description: "Professional services",
      quantity: 10,
      unit: "C62",
      unit_price: 100.00,
      amount: 1000.00,
      tax_rate: "21.00"
    }
  ],
  subtotal: 1000.00,
  total_tax: 210.00,
  invoice_total: 1210.00,
  amount_due: 1210.00,
  payment_term: "Payment within 30 days",
  payment_details: [
    {
      iban: "BE68539007547034",
      swift: "GEBABEBB",
      payment_reference: "INV-2026-001"
    }
  ]
};

const response = await fetch("https://api.e-invoice.be/api/documents/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(invoice),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result);

import os

import requests

invoice = {
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}

response = requests.post(
    "https://api.e-invoice.be/api/documents/",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    json=invoice,
    timeout=30,
)
if not response.ok:
    raise SystemExit(f"HTTP {response.status_code}: {response.text}")
print(response.json())

<?php
$invoice = [
  "document_type" => "INVOICE",
  "invoice_id" => "INV-2026-001",
  "invoice_date" => "2026-10-01",
  "due_date" => "2026-10-31",
  "currency" => "EUR",
  "purchase_order" => "PO-12345",
  "vendor_name" => "E-INVOICE BV",
  "vendor_tax_id" => "BE1018265814",
  "vendor_address" => "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email" => "billing@e-invoice.be",
  "customer_name" => "OpenPeppol VZW",
  "customer_tax_id" => "BE0848934496",
  "customer_address" => "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items" => [
    [
      "description" => "Professional services",
      "quantity" => 10,
      "unit" => "C62",
      "unit_price" => 100.00,
      "amount" => 1000.00,
      "tax_rate" => "21.00"
    ]
  ],
  "subtotal" => 1000.00,
  "total_tax" => 210.00,
  "invoice_total" => 1210.00,
  "amount_due" => 1210.00,
  "payment_term" => "Payment within 30 days",
  "payment_details" => [
    [
      "iban" => "BE68539007547034",
      "swift" => "GEBABEBB",
      "payment_reference" => "INV-2026-001"
    ]
  ]
];

$ch = curl_init("https://api.e-invoice.be/api/documents/");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("E_INVOICE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($invoice),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $body");
}
print_r(json_decode($body, true));

using System.Net.Http.Headers;
using System.Text;

var invoice = """
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}
""";

using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var response = await client.PostAsync(
    "/api/documents/",
    new StringContent(invoice, Encoding.UTF8, "application/json"));

var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {body}");
}
Console.WriteLine(body);

The API returns 201 Created with the complete document in the DRAFT state. Amounts are strings in the response. The response is shortened here.

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "created_at": "2026-10-01T09:15:23.482913Z",
  "document_type": "INVOICE",
  "state": "DRAFT",
  "direction": "OUTBOUND",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "subtotal": "1000.00",
  "total_tax": "210.00",
  "invoice_total": "1210.00",
  "amount_due": "1210.00"
}

Keep the id. You use it to send the document. If the API rejects the payload, see Create document errors.

Invoice structure

Main fields

Only the items array is mandatory in the schema. But the API accepts a document only if the generated UBL passes the Peppol BIS Billing 3.0 rules. Thus a complete invoice also needs the fields that this table marks as mandatory, the vendor and customer identifiers, and vendor_name. For the full list, see the document schema.

Field	Description	Mandatory
`items`	Array of invoice lines	Yes (minimum 1)
`document_type`	`INVOICE`, `CREDIT_NOTE`, `DEBIT_NOTE`, `SELFBILLING_INVOICE` or `SELFBILLING_CREDIT_NOTE`. Default: `INVOICE`. See Self-billing and debit notes.	No
`invoice_id`	Your unique invoice number	Yes (rule `BR-02`)
`invoice_date`	Invoice date (`YYYY-MM-DD`). Default: the current date.	Recommended
`due_date`	Payment due date (`YYYY-MM-DD`)	For an invoice with a positive amount due, `due_date` or `payment_term` is mandatory (rule `BR-CO-25`)
`currency`	Currency code, for example `EUR`. Default: `EUR`.	No

For all fields, see the document schema. For the amounts (subtotal, total_tax, invoice_total, amount_due), see Invoice totals and calculations.

Vendor fields

The vendor is the seller. This is your company.

Field	Description	Example
`vendor_name`	Company name	`"E-INVOICE BV"`
`vendor_tax_id`	VAT number with the country prefix	`"BE1018265814"`
`vendor_company_id`	Company registration number, for example the Belgian enterprise number	`"1018265814"`
`vendor_address`	Full address	`"Brusselsesteenweg 119/A, 1980 Zemst, BE"`
`vendor_email`	Contact email address	`"billing@e-invoice.be"`

The vendor_tax_id is the VAT number of the company. It is not the Peppol ID. For a Belgian company, give the full VAT number with the BE prefix, for example BE1018265814. The API derives the Peppol ID from it when you send the document.

Customer fields

The customer is the buyer.

Field	Description	Example
`customer_name`	Company name	`"OpenPeppol VZW"`
`customer_tax_id`	VAT number with the country prefix	`"BE0848934496"`
`customer_company_id`	Company registration number	`"0848934496"`
`customer_peppol_id`	Peppol ID of the customer (`scheme:identifier`)	`"0208:0848934496"`
`customer_address`	Full address	`"Robert Schumanplein 6 bus 5, 1040 Brussel, BE"`
`customer_email`	Contact email address	`"info@openpeppol.org"`

Line items

Each object in the items array is one product or service:

{
  "description": "Professional services",
  "quantity": 10,
  "unit": "C62",
  "unit_price": 100.00,
  "amount": 1000.00,
  "tax_rate": "21.00"
}

Field	Description
`description`	The product or service that you sell
`quantity`	Quantity
`unit`	Unit code. Frequent codes: `C62` (unit or piece), `HUR` (hour), `DAY` (day), `MTR` (metre), `KGM` (kilogram).
`unit_price`	Price for one unit, without VAT
`amount`	Line total without VAT: `quantity` x `unit_price`, minus the line allowances, plus the line charges. When a line has allowances or charges, you must send `amount`. See Line-level allowances.
`tax_rate`	VAT percentage from 0 to 100, as a number or a string, for example `21.00`, `"6.00"` or `"0.00"`

For all line fields, see the LineItem schema.

Optional fields

Payment details

{
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}

Additional addresses

Of these fields, only shipping_address and shipping_address_recipient go into the UBL (as the delivery). The API stores the billing, service and remittance addresses with the document, but the receiver does not get them.

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

Allowances and 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 Advanced invoicing.

References and notes

{
  "buyer_reference": "CC-4410",
  "purchase_order": "PO-12345",
  "sales_order": "SO-2026-0042",
  "note": "Thank you for your business"
}

buyer_reference is the reference that the buyer asks for (BT-10). When it is absent, the API writes purchase_order as the buyer reference. For the reference to a preceding invoice, see Create credit notes.

To send a PDF or a different file with the invoice, see Attachments and PDF.

Send the document

Send the document with POST /api/documents/{document_id}/send. Set the environment variable DOCUMENT_ID to the id from the create response. Replace the sender Peppol ID in the query with the Peppol ID of your company.

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

const documentId = process.env.DOCUMENT_ID; // the "id" from the create response

const query = new URLSearchParams({
  sender_peppol_scheme: "0208",
  sender_peppol_id: "1018265814",
  receiver_peppol_scheme: "0208",
  receiver_peppol_id: "0848934496",
});

const response = await fetch(
  `https://api.e-invoice.be/api/documents/${documentId}/send?${query}`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` },
  },
);

const result = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result.state);

import os

import requests

document_id = os.environ["DOCUMENT_ID"]  # the "id" from the create response

response = requests.post(
    f"https://api.e-invoice.be/api/documents/{document_id}/send",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    params={
        "sender_peppol_scheme": "0208",
        "sender_peppol_id": "1018265814",
        "receiver_peppol_scheme": "0208",
        "receiver_peppol_id": "0848934496",
    },
    timeout=30,
)
if not response.ok:
    raise SystemExit(f"HTTP {response.status_code}: {response.text}")
print(response.json()["state"])

<?php
$documentId = getenv("DOCUMENT_ID"); // the "id" from the create response

$query = http_build_query([
    "sender_peppol_scheme" => "0208",
    "sender_peppol_id" => "1018265814",
    "receiver_peppol_scheme" => "0208",
    "receiver_peppol_id" => "0848934496",
]);

$ch = curl_init("https://api.e-invoice.be/api/documents/$documentId/send?$query");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("E_INVOICE_API_KEY"),
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $body");
}
echo json_decode($body, true)["state"], PHP_EOL;

using System.Net.Http.Headers;

var documentId = Environment.GetEnvironmentVariable("DOCUMENT_ID"); // the "id" from the create response

using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var query = "sender_peppol_scheme=0208&sender_peppol_id=1018265814&receiver_peppol_scheme=0208&receiver_peppol_id=0848934496";

var response = await client.PostAsync($"/api/documents/{documentId}/send?{query}", null);

var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {body}");
}
Console.WriteLine(body);

The API returns 200 OK with the document. The state is now TRANSIT, because the delivery runs in the background. The response is shortened here.

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "created_at": "2026-10-01T09:15:23.482913Z",
  "document_type": "INVOICE",
  "state": "TRANSIT",
  "direction": "OUTBOUND",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "invoice_total": "1210.00"
}

For the errors of this call, see Send errors.

Peppol ID routing

When you send a document, the API finds each of the four Peppol values (sender scheme and identifier, receiver scheme and identifier) in this order:

The query parameter of the send request.
The Peppol ID that the API stored with the UBL of the document when you created it. For a document that you created from UBL, this is the cbc:EndpointID of the party.
The derivation from the identifiers in the document: customer_peppol_id first for the receiver, then vendor_company_id / customer_company_id and vendor_tax_id / customer_tax_id. For SELFBILLING_INVOICE and SELFBILLING_CREDIT_NOTE, the direction is reversed: the API derives the sender from the customer_* fields and the receiver from the vendor_* fields.

For a Belgian party, the API derives scheme 0208 and the enterprise number: the tax ID BE1018265814 gives the Peppol ID 0208:1018265814. If a tax ID has no country prefix, the API uses the country code at the end of the address (for example 1980 Zemst, BE). Always give the VAT number with its country prefix, because rule BR-CO-09 rejects a VAT number without it. For the scheme that the API derives in other countries, see Peppol ID schemes. When the API sends the document on the Peppol network, it writes the final sender and receiver values in the cbc:EndpointID elements of the UBL that it transmits. The other content of the UBL does not change. The derived scheme can be different from the scheme that the receiver registered. Thus the best practice is to give all four query parameters:

cURL

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

string

Scheme of the sender Peppol ID. Example: 0208.

string

Identifier of the sender, without the scheme. Example: 1018265814.

string

Scheme of the receiver Peppol ID. Example: 0208.

string

Identifier of the receiver, without the scheme. Example: 0848934496.

The API returns 400 if it cannot find a complete sender and receiver Peppol ID. It returns 409 if the sender Peppol ID is not one of the peppol_ids of your company.

Before you send, make sure that the receiver is registered on the Peppol network with the Peppol ID that you use. See Look up Peppol participants.

For the Peppol schemes and the check of a receiver, see Look up Peppol participants.

After the send request

The result depends on the type of company:

Production company: the API transmits the document on the Peppol network. The receiver gets it in the software that is connected to its Access Point.
Sandbox company: the API sends the UBL XML to the contact email address of the company. Nothing goes to the Peppol network. See What a send does in test mode.

The code is the same for the two types of company. Only the API key is different.

Document states

State	Meaning
`DRAFT`	The document exists but is not sent. `POST /api/documents/` always creates a document in this state.
`TRANSIT`	The send request is accepted and the transmission is in progress.
`SENT`	The transmission is complete.
`FAILED`	The transmission failed. You can send the document again.
`RECEIVED`	The document came in from another Peppol participant.

You can send a document only when it is in the DRAFT or FAILED state. For the transitions, the retry behaviour and the webhook events of each state, see Document lifecycle and delivery tracking. To follow the delivery, use webhooks or request GET /api/documents/{document_id} until the state is SENT or FAILED. If the state is FAILED, see A document is in state FAILED.

Complete example

These programs do the three steps in sequence. Save the example payload from Validate the invoice data as invoice.json, and replace the vendor fields and the Peppol IDs with your data.

Validate, create and send (Node.js and Python)

import { readFile } from "node:fs/promises";

const BASE_URL = "https://api.e-invoice.be";

async function post(path, body) {
  const response = await fetch(`${BASE_URL}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body,
  });
  const result = await response.json();
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
  }
  return result;
}

const invoice = await readFile("invoice.json", "utf8");

// 1. Validate (while you develop)
const validation = await post("/api/validate/json", invoice);
if (!validation.is_valid) {
  console.error("Validation failed:", validation.issues);
  process.exit(1);
}
console.log("OK: the invoice JSON is valid");

// 2. Create (same payload)
const document = await post("/api/documents/", invoice);
console.log("OK: document created:", document.id);

// 3. Send. Replace the Peppol IDs with those of your company and of the receiver.
const query = new URLSearchParams({
  sender_peppol_scheme: "0208",
  sender_peppol_id: "1018265814",
  receiver_peppol_scheme: "0208",
  receiver_peppol_id: "0848934496",
});
const sent = await post(`/api/documents/${document.id}/send?${query}`);
console.log("OK: send request accepted, state:", sent.state);

import json
import os
import sys

import requests

BASE_URL = "https://api.e-invoice.be"
HEADERS = {"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"}


def post(path, **kwargs):
    response = requests.post(f"{BASE_URL}{path}", headers=HEADERS, timeout=30, **kwargs)
    if not response.ok:
        raise SystemExit(f"HTTP {response.status_code}: {response.text}")
    return response.json()


with open("invoice.json") as f:
    invoice = json.load(f)

# 1. Validate (while you develop)
validation = post("/api/validate/json", json=invoice)
if not validation["is_valid"]:
    print("Validation failed:", validation["issues"])
    sys.exit(1)
print("OK: the invoice JSON is valid")

# 2. Create (same payload)
document = post("/api/documents/", json=invoice)
print("OK: document created:", document["id"])

# 3. Send. Replace the Peppol IDs with those of your company and of the receiver.
sent = post(
    f"/api/documents/{document['id']}/send",
    params={
        "sender_peppol_scheme": "0208",
        "sender_peppol_id": "1018265814",
        "receiver_peppol_scheme": "0208",
        "receiver_peppol_id": "0848934496",
    },
)
print("OK: send request accepted, state:", sent["state"])

Credit notes and other document types

A credit note has the same structure as an invoice. Set document_type to CREDIT_NOTE:

Credit note

{
  "document_type": "CREDIT_NOTE",
  "invoice_id": "CN-2026-001",
  "invoice_date": "2026-10-15",
  "due_date": "2026-11-14",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "preceding_invoice_id": "INV-2026-001",
  "preceding_invoice_date": "2026-10-01",
  "note": "Credit note for invoice INV-2026-001: 2 units returned",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services (credit)",
      "quantity": 2,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 200.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 200.00,
  "total_tax": 42.00,
  "invoice_total": 242.00,
  "amount_due": 242.00
}

This credit note has positive amounts. Replace the vendor fields with the data of your company. The API rejects a document if the Peppol ID of the vendor is not one of the peppol_ids of your company. See Create credit notes for partial credits and corrections, and Self-billing and debit notes for the other values of document_type.

Next Steps

Document lifecycle and delivery tracking

Follow the states and the delivery of a document

Look up Peppol participants

Find the Peppol ID of a customer

List, filter and manage documents

List, find and delete documents

Webhooks

Get a notification for each delivery result

Getting started

Send documents

Receive and manage

Other input formats

Integrate

SDKs and tools

Resellers

Reference

Overview

Before you start

Workflow

Validate the invoice data

Create the invoice

Invoice structure

Main fields

Vendor fields

Customer fields

Line items

Optional fields

Send the document

Peppol ID routing

After the send request

Document states

Complete example

Credit notes and other document types

Next Steps

Document lifecycle and delivery tracking

Look up Peppol participants

List, filter and manage documents

Webhooks

​Overview

​Before you start

​Workflow

​Validate the invoice data

​Create the invoice

​Invoice structure

​Main fields

​Vendor fields

​Customer fields

​Line items

​Optional fields

​Send the document

​Peppol ID routing

​After the send request

​Document states

​Complete example

​Credit notes and other document types

​Next Steps

Document lifecycle and delivery tracking

Look up Peppol participants

List, filter and manage documents

Webhooks

Overview

Before you start

Workflow

Validate the invoice data

Create the invoice

Invoice structure

Main fields

Vendor fields

Customer fields

Line items

Optional fields

Send the document

Peppol ID routing

After the send request

Document states

Complete example

Credit notes and other document types

Next Steps