Self-billing and debit notes

Overview

In a self-billing arrangement, the buyer issues the invoice in the name of the supplier. This guide shows how to create and receive self-billing invoices and self-billing credit notes, and how to create debit notes.

Document types

The document_type field accepts five values. The guides for invoices and credit notes cover the first two. This guide covers the other three.

`document_type`	Generated UBL	Type code	Your company is
`INVOICE`	`Invoice`	`380`	the vendor
`CREDIT_NOTE`	`CreditNote`	`381`	the vendor
`DEBIT_NOTE`	`Invoice`	`383`	the vendor
`SELFBILLING_INVOICE`	`Invoice`	`389`	the customer
`SELFBILLING_CREDIT_NOTE`	`CreditNote`	`261`	the customer

What self-billing is

In a self-billing arrangement, the buyer issues the invoice on behalf of the supplier. The supplier and the buyer agree on this arrangement before the first document is issued. The roles in the document do not change. The supplier is still the seller, and the buyer is still the party that pays. Only the issuer changes.

JSON fields	Party	In a self-billing document
`vendor_name`, `vendor_tax_id`, `vendor_address`, …	Supplier (seller)	Your trading partner
`customer_name`, `customer_tax_id`, `customer_address`, …	Buyer	Your company, which issues the document

Do not swap the parties to make the document look like a normal invoice. In a self-billing document, your company is in the customer_* fields and the supplier is in the vendor_* fields.

Ownership rule

The API derives two Peppol IDs from each document: one from the vendor_* identifiers and one from the customer_* identifiers. It then checks that your company owns one of them. The Peppol IDs of your company are in the peppol_ids field of GET /api/me/.

Document type	Peppol ID that must be in your `peppol_ids`
`INVOICE`, `CREDIT_NOTE`, `DEBIT_NOTE`	The ID derived from `vendor_tax_id` or `vendor_company_id`
`SELFBILLING_INVOICE`, `SELFBILLING_CREDIT_NOTE`	The ID derived from `customer_tax_id`, `customer_company_id` or `customer_peppol_id`

The comparison ignores letter case and surrounding spaces. If the check fails for a self-billing document, POST /api/documents/ returns 406 Not Acceptable:

{
  "detail": "Derived receiver '0208:0848934496' is not in tenant peppol_ids"
}

POST /api/documents/{document_id}/send does the same check and returns 409 Conflict with the same detail text.

The word “receiver” in this message refers to the party in the customer_* fields. The message means that the customer in your self-billing document is not your company. The most frequent cause is that the vendor and the customer are in the usual invoice order.

For the other three document types, the message is Derived sender '<scheme>:<id>' is not in tenant peppol_ids, and it refers to the party in the vendor_* fields.

Create a self-billing invoice

In this example, E-INVOICE BV (BE1018265814) is the buyer and issues the invoice. OpenPeppol VZW (BE0848934496) is the supplier. Save the payload as self-billing-invoice.json:

self-billing-invoice.json

{
  "document_type": "SELFBILLING_INVOICE",
  "invoice_id": "SB-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "OpenPeppol VZW",
  "vendor_tax_id": "BE0848934496",
  "vendor_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "customer_name": "E-INVOICE BV",
  "customer_tax_id": "BE1018265814",
  "customer_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "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": "SB-2026-001"
    }
  ]
}

The payment details in a self-billing invoice are those of the supplier, because the supplier receives the payment.

Validate the JSON

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.

curl -X POST "https://api.e-invoice.be/api/validate/json" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY" \
     -H "Content-Type: application/json" \
     -d @self-billing-invoice.json

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

const payload = await readFile("self-billing-invoice.json", "utf8");

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: payload,
});

const result = await response.json();
console.log(result.is_valid, result.issues);

import json
import os

import requests

with open("self-billing-invoice.json", encoding="utf-8") as f:
    payload = json.load(f)

response = requests.post(
    "https://api.e-invoice.be/api/validate/json",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    json=payload,
    timeout=30,
)

result = response.json()
print(result["is_valid"], result["issues"])

<?php
$payload = file_get_contents('self-billing-invoice.json');

$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 => $payload,
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

var_dump($result['is_valid'], $result['issues']);

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

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var payload = await File.ReadAllTextAsync("self-billing-invoice.json");
var content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api.e-invoice.be/api/validate/json", content);

Console.WriteLine(await response.Content.ReadAsStringAsync());

The API returns 201 Created:

{
  "id": "9eec0b03-4649-4ae4-9c4c-323ebb6d53e8",
  "file_name": "9eec0b03-4649-4ae4-9c4c-323ebb6d53e8.xml",
  "is_valid": true,
  "issues": [],
  "ubl_document": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\"..."
}

The API validates self-billing documents against a dedicated rule set, the Peppol BIS Self-Billing 3.0 schematron (PEPPOL-EN16931-UBL-SB), in place of the Peppol BIS Billing 3.0 schematron. The schematron field of each entry in issues shows the rule set that reported the issue.This endpoint does not apply the ownership rule. A payload can pass validation here and still get a 406 response when you create the document.

Create the document

The customer_tax_id must resolve to a Peppol ID of the company that owns the API key.

cURL

curl -X POST "https://api.e-invoice.be/api/documents/" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY" \
     -H "Content-Type: application/json" \
     -d @self-billing-invoice.json

Response (201 Created, shortened):

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "document_type": "SELFBILLING_INVOICE",
  "state": "DRAFT",
  "direction": "OUTBOUND",
  "invoice_id": "SB-2026-001",
  "vendor_name": "OpenPeppol VZW",
  "vendor_tax_id": "BE0848934496",
  "customer_name": "E-INVOICE BV",
  "customer_tax_id": "BE1018265814"
}

Send the document

cURL

curl -X POST "https://api.e-invoice.be/api/documents/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/send" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

Response (200 OK, shortened):

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "document_type": "SELFBILLING_INVOICE",
  "state": "TRANSIT",
  "direction": "OUTBOUND"
}

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.

Before you send self-billing documents from a production company, contact support@e-invoice.be to confirm the delivery route to your supplier. The API derives the Peppol sender from the vendor_* fields and the Peppol receiver from the customer_* fields for all document types.

Use the example in a sandbox company

The example uses the identity of E-INVOICE BV as the customer. In your own company, the create call returns 406 until the customer is your company. Replace the customer_* fields with the details of your company:

cURL

curl "https://api.e-invoice.be/api/me/" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

Response (shortened):

{
  "name": "My sandbox company",
  "company_tax_id": "BE0123456789",
  "company_email": "dev@example.com",
  "peppol_ids": ["0208:0123456789"]
}

Set customer_tax_id to a tax number that resolves to one of the peppol_ids values. For a Belgian company, the Peppol ID 0208:0123456789 corresponds to the tax number BE0123456789. See Test mode and sandbox companies.

Generated UBL identifiers

For both self-billing types, the generated UBL contains these identifiers:

UBL element	Value
`cbc:CustomizationID`	`urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0`
`cbc:ProfileID`	`urn:fdc:peppol.eu:2017:poacc:selfbilling:01:1.0`
`cbc:InvoiceTypeCode` (invoice)	`389`
`cbc:CreditNoteTypeCode` (credit note)	`261`

The supplier stays in cac:AccountingSupplierParty and your company stays in cac:AccountingCustomerParty.

Create self-billing documents from JSON. POST /api/documents/ubl stores an uploaded UBL file as INVOICE or CREDIT_NOTE and does not read the CustomizationID to set a self-billing type.

Check that the supplier can receive self-billing documents

A Peppol participant registers each document type that it can receive. Registration for Peppol BIS Billing 3.0 invoices does not include self-billing documents. Before you send, check the supplier with GET /api/validate/peppol-id:

cURL

curl "https://api.e-invoice.be/api/validate/peppol-id?peppol_id=0208:0848934496" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

Response:

{
  "is_valid": true,
  "dns_valid": true,
  "business_card_valid": true,
  "supported_document_types": [
    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1",
    "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1"
  ],
  "business_card": {
    "name": "OpenPeppol VZW",
    "country_code": "BE",
    "registration_date": "2021-06-15"
  }
}

Look in supported_document_types for these entries:

To send	Required entry contains
`SELFBILLING_INVOICE`	`Invoice-2::Invoice##` and `poacc:selfbilling:3.0`
`SELFBILLING_CREDIT_NOTE`	`CreditNote-2::CreditNote##` and `poacc:selfbilling:3.0`

If the entries are absent, the supplier cannot receive self-billing documents through Peppol. Ask the supplier to have the self-billing document types registered by its access point.

The response above is an illustration of the response shape. The document types of a real participant can be different.

Self-billing credit notes

Use SELFBILLING_CREDIT_NOTE to correct or cancel a self-billing invoice that your company issued. The parties are the same as in the self-billing invoice: the supplier is the vendor and your company is the customer. The ownership rule is also the same. The differences from the self-billing invoice example are:

Field	Self-billing credit note
`document_type`	`"SELFBILLING_CREDIT_NOTE"`
`invoice_id`	The credit note number, for example `SB-CN-2026-001`
`note`	The reason for the credit note (recommended)

{
  "document_type": "SELFBILLING_CREDIT_NOTE",
  "invoice_id": "SB-CN-2026-001",
  "invoice_date": "2026-10-05",
  "due_date": "2026-11-04",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "note": "Correction of self-billing invoice SB-2026-001: 2 units not delivered",
  "vendor_name": "OpenPeppol VZW",
  "vendor_tax_id": "BE0848934496",
  "vendor_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "customer_name": "E-INVOICE BV",
  "customer_tax_id": "BE1018265814",
  "customer_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 2,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 200.00,
      "tax_rate": "21.00"
    }
  ]
}

Amounts are positive, as in a standard credit note. See Create credit notes for the general rules.

Receive self-billing documents

When your company is the supplier, your buyer can send you self-billing documents. A company that is registered on Peppol through e-invoice.be is registered for the self-billing invoice and the self-billing credit note document types, together with the standard billing document types. The API reads the CustomizationID of each inbound UBL document. If the identifier is a self-billing identifier, the document gets the type SELFBILLING_INVOICE or SELFBILLING_CREDIT_NOTE. In an inbound self-billing document, your company is in the vendor_* fields and the buyer that issued the document is in the customer_* fields. Use the type filter on the inbox to list these documents:

cURL

curl "https://api.e-invoice.be/api/inbox/?type=SELFBILLING_INVOICE" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

Response (shortened):

{
  "items": [
    {
      "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "document_type": "SELFBILLING_INVOICE",
      "state": "RECEIVED",
      "direction": "INBOUND",
      "invoice_id": "SB-2026-001",
      "vendor_name": "E-INVOICE BV",
      "vendor_tax_id": "BE1018265814",
      "customer_name": "OpenPeppol VZW",
      "customer_tax_id": "BE0848934496"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "pages": 1,
  "has_next_page": false
}

The type filter on GET /api/inbox/, GET /api/outbox/ and GET /api/drafts/ accepts all five document types. In a sandbox company, Simulate inbound applies the same detection: a UBL file with a self-billing CustomizationID appears in the inbox with a self-billing type. See Receive documents for the complete inbound flow.

Debit notes

Set document_type to DEBIT_NOTE to create a debit note. The API handles a debit note in the same way as an invoice, with one difference in the generated UBL:

Aspect	`DEBIT_NOTE`
UBL document	`Invoice`
`cbc:InvoiceTypeCode`	`383` (an invoice has `380`)
`cbc:CustomizationID` and `cbc:ProfileID`	Same as an invoice (Peppol BIS Billing 3.0)
Validation rule set	Same as an invoice
Vendor and customer	Same as an invoice: your company is the vendor
Ownership rule	Same as an invoice: the vendor must be your company

All JSON fields, the totals calculation and the create and send calls are the same as for an invoice. A debit note increases the amount that the customer owes, so the amounts are positive.

{
  "document_type": "DEBIT_NOTE",
  "invoice_id": "DN-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "note": "Additional transport cost for invoice INV-2026-001",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Additional transport cost",
      "quantity": 1,
      "unit": "C62",
      "unit_price": 150.00,
      "amount": 150.00,
      "tax_rate": "21.00"
    }
  ],
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "DN-2026-001"
    }
  ]
}

Before you create this debit note, replace the vendor fields with the data of your company. Because a debit note is a UBL Invoice in the standard billing profile, a participant that can receive Peppol BIS Billing 3.0 invoices needs no additional registration to receive it.

An inbound UBL invoice with type code 383 appears in the inbox as INVOICE. The API does not derive the DEBIT_NOTE type from the type code of an inbound UBL document.

Frequently asked questions

Why does the create call return 406 with 'Derived receiver ... is not in tenant peppol_ids'?

The party in the customer_* fields of your self-billing document is not your company. In a self-billing document, put your company in the customer_* fields and the supplier in the vendor_* fields. Compare the ID in the message with the peppol_ids field of GET /api/me/.

Why does validation pass while the create call fails?

POST /api/validate/json checks the document content only. The ownership rule applies when you create and when you send the document.

Can I upload a self-billing UBL file?

POST /api/documents/ubl stores the document as INVOICE or CREDIT_NOTE. Create self-billing documents from JSON to get a self-billing document type.

Which party is in the vendor fields of a received self-billing invoice?

Your company. The buyer issued the document, but your company is the supplier, and the supplier is always in the vendor_* fields.

Next Steps

Create credit notes

Correct or cancel a standard invoice.

Receive documents

Process inbound documents, self-billing documents included.

Validation during development

Read validation issues and correct your JSON.

Look up Peppol participants

Check the document types that a participant can receive.

Getting started

Send documents

Receive and manage

Other input formats

Integrate

SDKs and tools

Resellers

Reference

Self-billing and debit notes

Overview

Document types

What self-billing is

Ownership rule

Create a self-billing invoice

Use the example in a sandbox company

Generated UBL identifiers

Check that the supplier can receive self-billing documents

Self-billing credit notes

Receive self-billing documents

Debit notes

Frequently asked questions

Next Steps

Create credit notes

Receive documents

Validation during development

Look up Peppol participants

​Overview

​Document types

​What self-billing is

​Ownership rule

​Create a self-billing invoice

​Use the example in a sandbox company

​Generated UBL identifiers

​Check that the supplier can receive self-billing documents

​Self-billing credit notes

​Receive self-billing documents

​Debit notes

​Frequently asked questions

​Next Steps

Create credit notes

Receive documents

Validation during development

Look up Peppol participants

Overview

Document types

What self-billing is

Ownership rule

Create a self-billing invoice

Use the example in a sandbox company

Generated UBL identifiers

Check that the supplier can receive self-billing documents

Self-billing credit notes

Receive self-billing documents

Debit notes

Frequently asked questions

Next Steps