When you create invoices via the Document API, tax codes from your source system often need to be enriched with e-invoicing tax category and exemption data. Document Tax Code Mappings let you maintain that mapping in the webportal — without a deployment — so Document API invoices get the correct tax category and exemption reason codes.

This configuration applies only to Document API requests. It does not replace Tax Exemptions used in tax rules for the billing run. For tax-rule exemptions, see VAT Categories and Tax Exemptions.

Open Document Tax Code Mappings

Navigate to: Configuration > Billing > Document Tax Code Mappings

The overview lists your existing mappings. An info banner on the page reminds you that the mapping is used for Document API enrichment.

Create a mapping

Click the add action to open Create Document Tax Code Mapping. Fill in the fields below, then save. Invalid or duplicate tax codes are rejected with an error message.

Tax Code

Your source tax code from the Document API payload (for example a code from your ERP). The value is stored in uppercase and must not start or end with whitespace. Once created, the tax code cannot be changed — create a new mapping if you need a different code.

Tax Category Code

The VAT category for e-invoicing (UNCL 5305 / EN 16931), for example S for standard rate or E for exempt. The field suggests the supported Peppol tax category codes as you type. See VAT Categories and Tax Exemptions for the category overview, and the Peppol UNCL5305 code list for the official definitions.

Tax Exemption Reason Code

Optional. The VATEX reason code when a zero or special VAT treatment applies (for example VATEX-EU-AE for reverse charge). The field suggests supported Peppol VATEX codes — see the Peppol VATEX code list. Align the reason code with the selected tax category.

Tax Exemption Reason

Optional. A human-readable explanation of the exemption. Use it when your e-invoicing profile expects a reason text in addition to the code.

Example

Your Document API payload sends tax code A7. You create a mapping with:

Tax Code: A7
Tax Category Code: S (standard rate)

For an exempt reverse-charge case you might map tax code RC01 to:

Tax Category Code: AE
Tax Exemption Reason Code: VATEX-EU-AE
Tax Exemption Reason: Reverse charge

After saving, subsequent Document API invoices that use these tax codes are enriched with the mapped category and exemption data.

Edit a mapping

Open the edit action on a row. You can change the tax category code, exemption reason code, and reason text. The tax code stays fixed. Save to apply the change immediately for subsequent Document API requests.

Delete a mapping

Use the delete action on a row and confirm. The mapping is removed immediately. Create it again if you still need it for Document API enrichment.

Via API

Document tax code mappings can also be maintained via API:

GET /v2/billing/configuration/document-tax-code-mappings — list mappings
POST /v2/billing/configuration/document-tax-code-mappings — create a mapping
PUT /v2/billing/configuration/document-tax-code-mappings/{taxCode} — update a mapping
DELETE /v2/billing/configuration/document-tax-code-mappings/{taxCode} — delete a mapping