API/Conversion

Convert a JSON invoice to Peppol UBL

POST/v1/conversions· API key

Turns a JSON invoice into a Peppol BIS Billing 3.0 UBL document, then validates the result against the full ruleset before returning it.

You supply the lines; the API computes every total and the VAT breakdown. Line identifiers are numbered from 1 if you omit them.

A conversion never returns an invalid document. If the invoice cannot produce one, the response is 422 with each problem mapped to the JSON field that caused it, alongside the rule it broke. Warnings do not block a conversion and are returned in validation.findings. Nothing is stored.

Request

curl -X POST https://api.einvoicing.dev/v1/conversions \  -H "Authorization: Bearer $EINVOICING_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "target": "peppol-bis-billing-3", "invoice": { "number": "INV-2026-0042", "issue_date": "2026-09-11", "due_date": "2026-10-11", "currency": "GBP", "buyer_reference": "PO-98765", "seller": { "name": "Acme Widgets Ltd", "electronic_address": { "scheme": "9932", "identifier": "GB123456789" }, "vat_number": "GB123456789", "company_number": "01234567", "address": { "lines": [ "Unit 4", "Mill Lane" ], "city": "Manchester", "postcode": "M1 1AA", "country_code": "GB" } }, "buyer": { "name": "Globex Trading Ltd", "electronic_address": { "scheme": "9932", "identifier": "GB987654321" }, "vat_number": "GB987654321", "address": { "lines": [ "1 Market Street" ], "city": "Leeds", "postcode": "LS1 1AA", "country_code": "GB" } }, "lines": [ { "name": "Consulting — September", "quantity": "10", "unit_code": "HUR", "unit_price": "100.00", "vat": { "category": "S", "rate": "20" } } ], "payment": { "method": "credit_transfer", "account": { "sort_code": "123456", "account_number": "12345678", "name": "Acme Widgets Ltd" }, "reference": "INV-2026-0042", "terms": "Payment within 30 days" } } }'

<?php$client = new GuzzleHttp\Client();$response = $client->request('POST', 'https://api.einvoicing.dev/v1/conversions', [    'headers' => [        'Authorization' => 'Bearer ' . getenv('EINVOICING_API_KEY'),        'Accept' => 'application/json',    ],    'json' => [        'target' => 'peppol-bis-billing-3',        'invoice' => [            'number' => 'INV-2026-0042',            'issue_date' => '2026-09-11',            'due_date' => '2026-10-11',            'currency' => 'GBP',            'buyer_reference' => 'PO-98765',            'seller' => [                'name' => 'Acme Widgets Ltd',                'electronic_address' => [                    'scheme' => '9932',                    'identifier' => 'GB123456789',                ],                'vat_number' => 'GB123456789',                'company_number' => '01234567',                'address' => [                    'lines' => [                        'Unit 4',                        'Mill Lane',                    ],                    'city' => 'Manchester',                    'postcode' => 'M1 1AA',                    'country_code' => 'GB',                ],            ],            'buyer' => [                'name' => 'Globex Trading Ltd',                'electronic_address' => [                    'scheme' => '9932',                    'identifier' => 'GB987654321',                ],                'vat_number' => 'GB987654321',                'address' => [                    'lines' => [                        '1 Market Street',                    ],                    'city' => 'Leeds',                    'postcode' => 'LS1 1AA',                    'country_code' => 'GB',                ],            ],            'lines' => [                [                    'name' => 'Consulting — September',                    'quantity' => '10',                    'unit_code' => 'HUR',                    'unit_price' => '100.00',                    'vat' => [                        'category' => 'S',                        'rate' => '20',                    ],                ],            ],            'payment' => [                'method' => 'credit_transfer',                'account' => [                    'sort_code' => '123456',                    'account_number' => '12345678',                    'name' => 'Acme Widgets Ltd',                ],                'reference' => 'INV-2026-0042',                'terms' => 'Payment within 30 days',            ],        ],    ],]);$data = json_decode((string) $response->getBody(), true)['data'];

payload := `{  "target": "peppol-bis-billing-3",  "invoice": {    "number": "INV-2026-0042",    "issue_date": "2026-09-11",    "due_date": "2026-10-11",    "currency": "GBP",    "buyer_reference": "PO-98765",    "seller": {      "name": "Acme Widgets Ltd",      "electronic_address": {        "scheme": "9932",        "identifier": "GB123456789"      },      "vat_number": "GB123456789",      "company_number": "01234567",      "address": {        "lines": [          "Unit 4",          "Mill Lane"        ],        "city": "Manchester",        "postcode": "M1 1AA",        "country_code": "GB"      }    },    "buyer": {      "name": "Globex Trading Ltd",      "electronic_address": {        "scheme": "9932",        "identifier": "GB987654321"      },      "vat_number": "GB987654321",      "address": {        "lines": [          "1 Market Street"        ],        "city": "Leeds",        "postcode": "LS1 1AA",        "country_code": "GB"      }    },    "lines": [      {        "name": "Consulting — September",        "quantity": "10",        "unit_code": "HUR",        "unit_price": "100.00",        "vat": {          "category": "S",          "rate": "20"        }      }    ],    "payment": {      "method": "credit_transfer",      "account": {        "sort_code": "123456",        "account_number": "12345678",        "name": "Acme Widgets Ltd"      },      "reference": "INV-2026-0042",      "terms": "Payment within 30 days"    }  }}`req, _ := http.NewRequest(http.MethodPost, "https://api.einvoicing.dev/v1/conversions", strings.NewReader(payload))req.Header.Set("Authorization", "Bearer "+os.Getenv("EINVOICING_API_KEY"))req.Header.Set("Content-Type", "application/json")res, err := http.DefaultClient.Do(req)if err != nil {	log.Fatal(err)}defer res.Body.Close()

const res = await fetch("https://api.einvoicing.dev/v1/conversions", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.EINVOICING_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    "target": "peppol-bis-billing-3",    "invoice": {      "number": "INV-2026-0042",      "issue_date": "2026-09-11",      "due_date": "2026-10-11",      "currency": "GBP",      "buyer_reference": "PO-98765",      "seller": {        "name": "Acme Widgets Ltd",        "electronic_address": {          "scheme": "9932",          "identifier": "GB123456789"        },        "vat_number": "GB123456789",        "company_number": "01234567",        "address": {          "lines": [            "Unit 4",            "Mill Lane"          ],          "city": "Manchester",          "postcode": "M1 1AA",          "country_code": "GB"        }      },      "buyer": {        "name": "Globex Trading Ltd",        "electronic_address": {          "scheme": "9932",          "identifier": "GB987654321"        },        "vat_number": "GB987654321",        "address": {          "lines": [            "1 Market Street"          ],          "city": "Leeds",          "postcode": "LS1 1AA",          "country_code": "GB"        }      },      "lines": [        {          "name": "Consulting — September",          "quantity": "10",          "unit_code": "HUR",          "unit_price": "100.00",          "vat": {            "category": "S",            "rate": "20"          }        }      ],      "payment": {        "method": "credit_transfer",        "account": {          "sort_code": "123456",          "account_number": "12345678",          "name": "Acme Widgets Ltd"        },        "reference": "INV-2026-0042",        "terms": "Payment within 30 days"      }    }  }),});const { data } = await res.json();

Request body

application/json· required

Field	Type	Description
`target`required	string	The document format to produce. Peppol BIS Billing 3.0 UBL is the only target in this version. `peppol-bis-billing-3`
`ruleset`	string	Pin post-conversion validation to a ruleset `id`. Omit for the current ruleset.
`invoice`required	Invoice	An invoice or credit note in plain JSON. Field descriptions give the EN 16931 business term each maps to. Totals and the VAT breakdown are not accepted here; they are computed from `lines`.

Example bodyapplication/json

{  "target": "peppol-bis-billing-3",  "invoice": {    "number": "INV-2026-0042",    "issue_date": "2026-09-11",    "due_date": "2026-10-11",    "currency": "GBP",    "buyer_reference": "PO-98765",    "seller": {      "name": "Acme Widgets Ltd",      "electronic_address": {        "scheme": "9932",        "identifier": "GB123456789"      },      "vat_number": "GB123456789",      "company_number": "01234567",      "address": {        "lines": [          "Unit 4",          "Mill Lane"        ],        "city": "Manchester",        "postcode": "M1 1AA",        "country_code": "GB"      }    },    "buyer": {      "name": "Globex Trading Ltd",      "electronic_address": {        "scheme": "9932",        "identifier": "GB987654321"      },      "vat_number": "GB987654321",      "address": {        "lines": [          "1 Market Street"        ],        "city": "Leeds",        "postcode": "LS1 1AA",        "country_code": "GB"      }    },    "lines": [      {        "name": "Consulting — September",        "quantity": "10",        "unit_code": "HUR",        "unit_price": "100.00",        "vat": {          "category": "S",          "rate": "20"        }      }    ],    "payment": {      "method": "credit_transfer",      "account": {        "sort_code": "123456",        "account_number": "12345678",        "name": "Acme Widgets Ltd"      },      "reference": "INV-2026-0042",      "terms": "Payment within 30 days"    }  }}

Response

200

The invoice was converted and the document passed validation.

Field	Type	Description
`data`required	Conversion	The produced document, what was computed for it, and its validation report.

Example responseapplication/json

{  "data": {    "target": "peppol-bis-billing-3",    "document": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\" …>\n  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>\n  <cbc:ID>INV-2026-0042</cbc:ID>\n  …\n</Invoice>\n",    "totals": {      "line_extension": "1000.00",      "tax_exclusive": "1000.00",      "tax": "200.00",      "tax_inclusive": "1200.00",      "payable": "1200.00"    },    "vat_breakdown": [      {        "category": "S",        "rate": "20",        "taxable_amount": "1000.00",        "tax_amount": "200.00",        "exemption_reason": null,        "exemption_reason_code": null      }    ],    "validation": {      "valid": true,      "ruleset": {        "id": "peppol-bis-billing-3.0.21",        "version": "3.0.21"      },      "document": {        "type": "invoice",        "customization_id": "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0",        "profile_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"      },      "layers": [        {          "name": "xsd",          "status": "passed"        },        {          "name": "en16931",          "status": "passed"        },        {          "name": "peppol",          "status": "passed"        }      ],      "summary": {        "errors": 0,        "warnings": 0      },      "findings": []    }  }}

Errors

Every error is application/problem+json (RFC 9457). Branch on type, which is stable, never on title or detail.

Status	When
400	The body could not be parsed as the XML or JSON its `Content-Type` declares. Distinct from `422`, which means the body parsed and its contents were rejected. Problem `type` is `malformed-body`. /problems/malformed-body
401	No key, or a key that is unknown or revoked. Problem `type` is `unauthenticated`. /problems/unauthenticated
402	The Free plan's monthly allowance for this operation is used up. This is a billing state, not a rate limit: waiting will not help until the period resets or the plan changes. Paid plans never receive it. Problem `type` is `allowance-exhausted`. /problems/allowance-exhausted
413	The body is larger than 5 MiB. Problem `type` is `payload-too-large`. /problems/payload-too-large
415	The `Content-Type` is not one this operation accepts. Problem `type` is `unsupported-media-type`.
422	The body parsed but cannot produce a valid document. Problem `type` is `invalid-request` when the JSON does not match this schema (including unknown fields, which are refused rather than silently dropped), and `invalid-invoice` when it matches but breaks an e-invoicing rule.
429	Too many requests in a short window. Slow down and retry after the number of seconds in `Retry-After`. Problem `type` is `rate-limited`. /problems/rate-limited
503	The validator could not judge the document. The fault is on our side, not in the document, and nothing was stored. It is never reported as valid or invalid. Retry after the number of seconds in `Retry-After`. Problem `type` is `validator-unavailable`. /problems/validator-unavailable

Schemas

ConversionRequest

A JSON invoice and the format to produce.

Field	Type	Description
`target`required	string	The document format to produce. Peppol BIS Billing 3.0 UBL is the only target in this version. `peppol-bis-billing-3`
`ruleset`	string	Pin post-conversion validation to a ruleset `id`. Omit for the current ruleset.
`invoice`required	Invoice	An invoice or credit note in plain JSON. Field descriptions give the EN 16931 business term each maps to. Totals and the VAT breakdown are not accepted here; they are computed from `lines`.

Invoice

An invoice or credit note in plain JSON. Field descriptions give the EN 16931 business term each maps to. Totals and the VAT breakdown are not accepted here; they are computed from `lines`.

Field	Type	Description
`type`	string	Invoice (type code 380) or credit note (381). BT-3. `invoicecredit_note`
`number`required	string	The invoice number. BT-1.
`issue_date`required	string · date	BT-2.
`due_date`	string or null · date	BT-9.
`currency`required	string	ISO 4217 currency code. BT-5.
`buyer_reference`	string or null	The buyer's own reference. BT-10. Peppol requires this or `order_reference` (rule PEPPOL-EN16931-R003).
`order_reference`	string or null	The buyer's purchase order number. BT-13.
`preceding_invoice`	object or null	The invoice a credit note corrects. BG-3.
`number`required	string	BT-25.
`issue_date`	string or null · date	BT-26.
`note`	string or null	Free-text note. BT-22.
`seller`required	Party	A seller (BG-4) or buyer (BG-7).
`buyer`required	Party	A seller (BG-4) or buyer (BG-7).
`lines`required	InvoiceLine[]	The invoice lines. BG-25.
`payment`	Payment	How to pay. BG-16.

Conversion

The produced document, what was computed for it, and its validation report.

Field	Type	Description
`target`required	string	The format produced. `peppol-bis-billing-3`
`document`required	string	The UBL 2.1 XML document, ready to hand to an Access Point.
`totals`required	Totals	Document totals, computed from the lines. BG-22.
`vat_breakdown`required	VatBreakdown[]	The computed VAT breakdown. BG-23.
`validation`required	ValidationReport	The outcome of validating one document.