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
Thedocument_type field accepts five values. The guides for invoices and credit notes cover the first two. This guide covers the other three.
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.Ownership rule
The API derives two Peppol IDs from each document: one from thevendor_* identifiers and one from the customer_* identifiers. The party that issues the document is the Peppol sender, and the other party is the Peppol receiver. The API checks that the sender Peppol ID is one of the Peppol IDs of your company. The Peppol IDs of your company are in the peppol_ids field of GET /api/me/.
The comparison ignores letter case and surrounding spaces.
If the check fails,
POST /api/documents/ returns 406 Not Acceptable. For a self-billing document, the ID in the message comes from the customer_* fields:
POST /api/documents/{document_id}/send does the same check and returns 409 Conflict with the same detail text.
The word “sender” in this message refers to the Peppol sender, not to the vendor. In a self-billing document, the Peppol sender is the party in the
customer_* fields. If the ID in the message is the ID of your supplier, the vendor and the customer are in the usual invoice order. Put your company in the customer_* 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
The payment details in a self-billing invoice are those of the supplier, because the supplier receives the payment.
1
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.201 Created: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.2
Create the document
The Response (
customer_tax_id must resolve to a Peppol ID of the company that owns the API key.cURL
201 Created, shortened):3
Send the document
The sender is your company (the Response (
customer_* fields). The receiver is the supplier (the vendor_* fields).cURL
200 OK, shortened):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.
customer_* fields) to the supplier (the vendor_* fields). In the query parameters of the send request, sender_peppol_* is the Peppol ID of your company and receiver_peppol_* is the Peppol ID of the supplier. See Peppol ID routing.
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 returns406 until the customer is your company. Replace the customer_* fields with the details of your company:
cURL
customer_tax_id to a tax number that resolves to one of the peppol_ids values. For a Belgian company, the Peppol ID 0208:1018265814 corresponds to the tax number BE1018265814. See Test mode and sandbox companies.
Generated UBL identifiers
For both self-billing types, the generated UBL contains these identifiers:
The supplier stays in
cac:AccountingSupplierParty and your company stays in cac:AccountingCustomerParty.
You can also upload a self-billing UBL file with
POST /api/documents/ubl. The API reads the CustomizationID of the file. A file with the self-billing CustomizationID gets the type SELFBILLING_INVOICE or SELFBILLING_CREDIT_NOTE.The API validates the file before it reads the CustomizationID. A CustomizationID that is not the self-billing identifier and does not start with the billing identifier fails rule PEPPOL-EN16931-R004 (a self-billing identifier with an extension also fails this rule), and the API returns 415 with the detail UBL file is not valid and contains errors. A CustomizationID that passes this rule but that the API does not know gives 422, for example a billing identifier with an extension: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 withGET /api/validate/peppol-id:
cURL
supported_document_types for these entries:
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
UseSELFBILLING_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:
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 theCustomizationID 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
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
Setdocument_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:
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.
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 sender ... is not in tenant peppol_ids'?
Why does the create call return 406 with 'Derived sender ... is not in tenant peppol_ids'?
In a self-billing document, the Peppol sender is the party in the
customer_* fields, and that party is not your company. 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?
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?
Can I upload a self-billing UBL file?
Yes.
POST /api/documents/ubl reads the CustomizationID of the file and stores a self-billing file as SELFBILLING_INVOICE or SELFBILLING_CREDIT_NOTE.Which party is in the vendor fields of a received self-billing invoice?
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.