Peppox API — API Documentation

Authentication

Type
APIKEY — API KEY
Location
query / param: apikey
Fallback via query/body param "apikey"
GET /sendsms/?apikey=YOUR_API_KEY

Invoice Management

/invoice/add • Methods: POST

Add a sales invoice header

Creates a new invoice header in DRAFT status. The endpoint records all supplier and customer information, issue dates, payment terms, and delivery details. Supplier data are automatically loaded from your API key registration (customer_api).
POST /invoice/add • Rate: 60 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key (from your registered supplier account).
network string No Optional network identifier (Peppol by default).
inv_id string No Optional internal invoice number.
issue_date string Yes Invoice issue date (YYYY-MM-DD).
due_date string No Invoice due date (YYYY-MM-DD).
invoice_type_code string No 380 Peppol invoice type code (e.g. 380 = Invoice, 381 = CreditNote).
currency string No EUR ISO currency code.
accounting_cost string No Internal accounting code reference.
buyer_reference string No Buyer reference / PO number.
payment.means_code string No 1 Means of payment (Peppol code list).
payment.payment_id string No Payment identifier / reference.
payment.iban string No Payee IBAN.
payment.account_name string No Payee account holder name.
payment.bic string No Payee BIC/SWIFT code.
payment.terms_note string No Payment terms note.
delivery.date string No Delivery date.
delivery.location_scheme string No 0088 Delivery location scheme identifier.
delivery.location_id string No Delivery location ID.
delivery.street string No Delivery address street.
delivery.city string No Delivery address city.
delivery.postal string No Delivery address postal code.
delivery.country string No Delivery address country code.
delivery.party_name string No Delivery party name.
customer.endpoint_scheme string No 0208 Customer Peppol scheme ID.
customer.endpoint_id string No Customer Peppol Participant ID.
customer.name string No Customer name.
customer.street string No Customer street.
customer.city string No Customer city.
customer.postal string No Customer postal code.
customer.country string No Customer country code.
customer.vat_id string No Customer VAT number.
customer.company_id_scheme string No 0208 Customer company ID scheme.
customer.company_id string No Customer company ID (national number).
customer.phone string No Customer contact phone.
customer.email string No Customer contact email.

Request examples

CURL
PYTHON
curl -X POST "https://api.peppox.com/invoice/add/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d "{ "issue_date": "2025-10-17", "due_date": "2025-11-17", "customer": { "endpoint_id": "9915:BE0123456789", "name": "ACME SPRL", "country": "BE" }, "payment": { "iban": "BE12345678901234", "bic": "GEBABEBB", "account_name": "Peppox Supplier" } }"

Responses

Status: 200 — Invoice successfully created (draft).
JSON
{ "ok": true, "invoice_guid": "inv-8c3b4a99-2025-10-17", "status": "DRAFT" }
Status: 400 — Invalid or missing fields.
Status: 401 — Invalid or expired API key.
Status: 500 — Internal server or database error.
/invoice_line/add • Methods: POST

Add an invoice line to an existing invoice

Adds a new line to an existing invoice (identified by invoice_guid). Supports unit, quantity, price, VAT category, and product identification codes.
POST /invoice_line/add • Rate: 60 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key (required for authentication).
invoice_guid string Yes The unique invoice GUID returned from /invoice/add.
line_id string No Optional internal line identifier (defaults to generated GUID).
quantity number Yes Quantity of the item or service.
unit_code string No Unit code according to UNECE Rec 20 (e.g. H87 for “piece”).
price_amount number Yes Unit price (excluding tax).
item_description string No Description of the item or service.
item_name string No Item name or title.
seller_item_id string No Seller internal item ID or SKU.
std_item_id_scheme string No 0088 Standard scheme ID for item identification (e.g. GTIN).
std_item_id string No Standardized item ID (GTIN, EAN, etc.).
origin_country string No Country of origin (ISO 3166-1 alpha-2).
tax_category string No VAT category code (e.g. S, Z, AE).
tax_percent number No VAT rate percentage (e.g. 21.00).

Request examples

CURL
PYTHON
curl -X POST "https://api.peppox.com/invoice_line/add/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d "{ "invoice_guid": "inv-8c3b4a99-2025-10-17", "quantity": 2, "unit_code": "H87", "price_amount": 49.99, "item_name": "Consulting service", "tax_percent": 21 }"

Responses

Status: 200 — Invoice line successfully added.
JSON
{ "ok": true, "line_guid": "line-2b4fa3c1-2025-10-17" }
Status: 400 — Invalid parameters (missing invoice_guid or invalid numeric fields).
Status: 401 — Invalid or expired API key.
Status: 500 — Internal database or server error.
/invoice_attach_pdf/add • Methods: POST

Attach a PDF to an existing invoice

Attaches a PDF document (via upload, Base64, or remote URL) to an existing invoice identified by invoice_guid. Only one attachment per invoice is stored; any previous file is replaced.
POST /invoice_attach_pdf/add • Rate: 30 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key (authentication).
invoice_guid string Yes The GUID of the invoice to attach the PDF to.
doc_id string No Optional document identifier (defaults to invoice ID or a generated UUID).
filename string No attachment.pdf Attachment file name (e.g. invoice.pdf).
mime string No application/pdf MIME type of the file.
content_base64 string No PDF content as Base64 string. Accepts data URI format.
file_url string No Remote HTTPS URL of a PDF to download and attach.
file file No File upload field (multipart/form-data).

Request examples

CURL
CURL
CURL
curl -X POST "https://api.peppox.com/invoice_attach_pdf/add/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "invoice_guid=inv-8c3b4a99-2025-10-17" \ -F "file=@invoice.pdf"

Responses

Status: 200 — PDF successfully attached to the invoice.
JSON
{ "ok": true, "invoice_guid": "inv-8c3b4a99-2025-10-17", "doc_id": "DOC-1452", "filename": "invoice-2025-10.pdf", "mime": "application/pdf", "size_bytes": 184527 }
Status: 400 — Invalid parameters or missing content (no Base64, file, or URL).
Status: 401 — Invalid or expired API key.
Status: 404 — Invoice not found.
Status: 500 — Internal server or database error.

XML Generation

/xml/generate • Methods: POST

Generate a UBL XML file for an invoice or Credit Note

Combines invoice/credit note header, lines, and attached PDF (if any) into a Peppol-compliant UBL 3.0 XML document. Returns the local path to the generated file and updates the invoice/credit note status to XML_BUILT.
POST /xml/generate • Rate: 30 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key for authentication.
invoice_guid string Yes The unique identifier of the invoice to convert to XML.
guid string No Alternative key for invoice_guid.

Request examples

CURL
PYTHON
curl -X POST "https://api.peppox.com/xml/generate/" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d "{ "invoice_guid": "inv-8c3b4a99-2025-10-17" }"

Responses

Status: 200 — XML successfully generated and stored on server.
JSON
{ "ok": true, "status": "XML_BUILT", "xml_path": "/var/www/vhosts/peppox.com/httpdocs/invoices_xml/inv-8c3b4a99-2025-10-17.xml" }
Status: 400 — Missing invoice_guid or invoice lines.
Status: 401 — Invalid or expired API key.
Status: 404 — Invoice not found.
Status: 500 — Internal XML generation or write error.

Credit Notes

/creditnote/add • Methods: POST

Add a credit note header

Creates a new credit note header in DRAFT status. Supplier data are automatically loaded from the API key account, while customer, payment, and delivery fields are accepted from the request.
POST /creditnote/add • Rate: 60 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key.
network string No Optional network identifier.
creditnote_id string No Preferred credit note number/identifier.
cn_id string No Alternative alias for credit note ID.
credit_note_id string No Alternative alias for credit note ID.
inv_id string No Alternative legacy identifier.
issue_date string Yes Credit note issue date (YYYY-MM-DD).
due_date string No Due date (YYYY-MM-DD).
invoice_type_code string No 381 Document type code. Default 381 = Credit Note.
currency string No EUR ISO currency code.
accounting_cost string No Internal accounting reference.
buyer_reference string No Buyer reference / customer PO reference.
payment.means_code string No 1 Payment means code.
payment.payment_id string No Payment reference.
payment.iban string No Payee IBAN.
payment.account_name string No Payee account name.
payment.bic string No Payee BIC / SWIFT.
payment.terms_note string No Payment terms note.
delivery.date string No Delivery date.
delivery.location_scheme string No 0088 Delivery location scheme.
delivery.location_id string No Delivery location identifier.
delivery.street string No Delivery street.
delivery.city string No Delivery city.
delivery.postal string No Delivery postal code.
delivery.country string No Delivery country code.
delivery.party_name string No Delivery party name.
supplier.endpoint_scheme string No 0208 Supplier endpoint scheme. Supplier values are otherwise loaded from the API account.
customer.endpoint_scheme string No 0208 Customer endpoint scheme.
customer.endpoint_id string No Customer endpoint ID.
customer.name string No Customer legal name.
customer.street string No Customer street.
customer.city string No Customer city.
customer.postal string No Customer postal code.
customer.country string No Customer country code.
customer.vat_id string No Customer VAT number.
customer.company_id_scheme string No 0208 Customer company ID scheme.
customer.company_id string No Customer company ID.
customer.phone string No Customer phone.
customer.email string No Customer email.

Request examples

CURL
PYTHON
curl -X POST "https://api.peppox.com/creditnote/add/" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{ "creditnote_id": "CN-2025-001", "issue_date": "2025-10-17", "currency": "EUR", "customer": { "endpoint_id": "9915:BE0123456789", "name": "ACME SPRL", "country": "BE" } }"

Responses

Status: 200 — Credit note successfully created.
JSON
{ "ok": true, "invoice_guid": "cn-8c3b4a99-2025-10-17", "document_type": "CREDIT_NOTE", "status": "DRAFT" }
Status: 400 — Invalid or missing fields.
Status: 401 — Invalid or expired API key.
Status: 500 — Internal server or database error.
/creditnote_line/add • Methods: POST

Add a credit note line

Adds a line to an existing credit note. Automatically accepts aliases for creditnote_guid and computes tax_category from tax_percent when possible.
POST /creditnote_line/add • Rate: 60 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key.
creditnote_guid string Yes The target credit note GUID.
invoice_guid string No Alias for creditnote_guid.
guid string No Alias for creditnote_guid.
line_id string No Optional internal line identifier.
order_line_id string No Alias for line_id.
quantity number Yes Line quantity.
qty number No Alias for quantity.
q number No Alias for quantity.
unit_code string No Unit code.
unit string No Alias for unit_code.
u string No Alias for unit_code.
price_amount number Yes Unit price amount.
price number No Alias for price_amount.
unit_price number No Alias for price_amount.
item_description string No Line description.
description string No Alias for item_description.
desc string No Alias for item_description.
item_name string No Item name/title.
name string No Alias for item_name.
title string No Alias for item_name.
seller_item_id string No Seller item ID / SKU.
seller_id string No Alias for seller_item_id.
sku string No Alias for seller_item_id.
std_item_id_scheme string No 0088 Standard item identification scheme.
std_scheme string No Alias for std_item_id_scheme.
scheme string No Alias for std_item_id_scheme.
std_item_id string No Standard item ID (EAN, GTIN, etc.).
gtin string No Alias for std_item_id.
ean string No Alias for std_item_id.
origin_country string No Country of origin.
country string No Alias for origin_country.
tax_category string No VAT category code. Automatically forced to S or Z depending on tax_percent.
tax_cat string No Alias for tax_category.
vat_category string No Alias for tax_category.
tax_percent number No VAT percentage.
vat_rate number No Alias for tax_percent.
tax number No Alias for tax_percent.
vat number No Alias for tax_percent.

Request examples

CURL
PYTHON
curl -X POST "https://api.peppox.com/creditnote_line/add/" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{ "creditnote_guid": "cn-8c3b4a99-2025-10-17", "quantity": 2, "unit_code": "H87", "price_amount": 49.99, "item_name": "Returned consulting service", "tax_percent": 21 }"

Responses

Status: 200 — Credit note line successfully added.
JSON
{ "ok": true, "line_guid": "line-2b4fa3c1-2025-10-17" }
Status: 400 — Missing required values such as creditnote_guid, quantity, or price_amount.
Status: 401 — Invalid or expired API key.
Status: 500 — Internal database error.
/creditnote_attach_pdf/add • Methods: POST

Attach a PDF to a credit note

Attaches a PDF document to an existing credit note using multipart upload, Base64 payload, or remote URL. Previous attachment is replaced.
POST /creditnote_attach_pdf/add • Rate: 30 req/min • Auth required

Parameters

NameInTypeRequiredDefaultDescription
apikey string Yes Your Peppox API key.
creditnote_guid string Yes The credit note GUID to attach the PDF to.
invoice_guid string No Alias for creditnote_guid.
guid string No Alias for creditnote_guid.
doc_id string No Optional document identifier. Defaults to inv_id or a generated UUID.
filename string No attachment.pdf Attachment filename.
mime string No application/pdf Attachment MIME type.
content_base64 string No PDF content encoded as Base64.
pdf_base64 string No Alias for content_base64.
file_url string No HTTP/HTTPS URL of the PDF to download and attach.
pdf_url string No Alias for file_url.
file file No Multipart uploaded file.

Request examples

CURL
CURL
CURL
curl -X POST "https://api.peppox.com/creditnote_attach_pdf/add/" -H "Authorization: Bearer YOUR_API_KEY" -F "creditnote_guid=cn-8c3b4a99-2025-10-17" -F "file=@creditnote.pdf"

Responses

Status: 200 — PDF successfully attached to the credit note.
JSON
{ "ok": true, "creditnote_guid": "cn-8c3b4a99-2025-10-17", "doc_id": "CN-2025-001", "filename": "creditnote.pdf", "mime": "application/pdf", "size_bytes": 184527 }
Status: 400 — Invalid request: missing creditnote_guid, invalid Base64, invalid URL, or no content provided.
Status: 401 — Invalid or expired API key.
Status: 404 — Credit note not found.
Status: 500 — Internal database or file handling error.

Webhooks

No webhooks documented.

SDKs

No SDKs listed.

Error catalog

No errors defined.

Changelog

No releases yet.
Generated from database • Peppox API • All rights reserved.