E-invoicing: Peppol for Magento 2: User Guide

Send Peppol BIS Billing 3.0 e-invoices and credit notes from Magento over the Peppol network. Documents are created from your Magento invoices and credit memos, checked against the Peppol and EN 16931 rules, the buyer is looked up on the Peppol network, and your access point provider (e-invoice.be, Recommand or Storecove) delivers them. Every step is recorded in an audit trail.

This package adds Peppol to E-Invoicing Core (commercegears/module-e-invoicing-core, free), which provides the queue, the admin grid, the document page, validation and the checkout fields.

• Storefront demo (sign in as the demo customer, then My Orders): https://demo.commercegears.com/customer/account/login/ and on Hyvä https://demo.commercegears.com/hyva/customer/account/login/
• Admin demo: https://demo.commercegears.com/try-admin/e-invoicing-peppol
• Changelog: Release notes · Questions: FAQ

On the demo the documents are generated and validated in the store. The demo is connected to an e-invoice.be sandbox company: a document sent from the demo goes to e-invoice.be, which e-mails it to the sandbox company's own address instead of using Peppol. Rejected and failed states in the demo are demo records, marked as such in the audit trail.

1. Requirements

The providers are beta. e-invoice.be is tested end to end with an e-invoice.be sandbox company (which does not use Peppol). Recommand and Storecove are built from the providers' API documentation and tested with a mock transport. Test with the provider's sandbox before going live.

Peppol in practice: in Belgium, invoices between Belgian VAT-registered businesses must be structured e-invoices from 1 January 2026, with Peppol BIS as the standard. Elsewhere Peppol is used mainly for invoices to public bodies and by businesses that choose it. The module sends; receiving supplier invoices is done in your provider's account.

2. Installation

With Composer. Use the Composer keys from your account on commercegears.com (see https://commercegears.com/composer-access/):

composer config repositories.commercegears composer https://repo.commercegears.com
composer config --auth http-basic.repo.commercegears.com PUBLIC_KEY PRIVATE_KEY
composer require commercegears/module-e-invoicing-peppol
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

E-Invoicing Core is installed with it. Magento's cron must run: documents are generated, sent and checked by the cron job every 5 minutes.

3. Quick start

1. Stores > Configuration > CommerceGears > E-Invoicing > General > Enabled = Yes.
2. In Seller (Your Company) fill in your legal name, VAT ID and address, and your own Peppol ID: Electronic Address Scheme (for example 0208 in Belgium) and Electronic Address ID (e.g. Peppol ID) without the scheme, as given by your access point provider.
3. Stores > Configuration > CommerceGears > E-Invoicing: Peppol: choose the Access Point Provider and the Environment (Sandbox / Test first), enter the API Key (and for Recommand the API Secret, for Recommand and Storecove the Company / Legal Entity ID), save and click Test Connection.
4. Invoice an order of a Belgian or Dutch business customer. Cron generates the Peppol BIS document, checks it and sends it through your provider.

4. Configuration

E-Invoicing: Peppol (section commercegears_einvoicing_peppol, paths commercegears_einvoicing/peppol/*, default and website scope):

Where to find the keys: e-invoice.be creates the API key in your e-invoice.be account (a key of a sandbox company sends to the sandbox, which e-mails the document instead of using Peppol). Your Peppol ID in the seller settings must be one of the account's Peppol IDs; Test Connection shows them. Recommand shows the API key, secret and company ID in its dashboard (use a playground team for testing). Storecove shows the API key and the legal entity ID of your company in your Storecove account.

E-Invoicing (Core settings, section commercegears_einvoicing): Enabled, Send Automatically (default Yes: valid documents are sent by cron; No: send them from the grid), your seller details including the Peppol ID, the rules under Countries, Formats and Delivery, payment terms, VAT categories, Ask for E-Invoice Details at checkout and Download in Customer Account.

Suggested rules (used until you save your own): Belgian businesses and Dutch businesses get Peppol BIS over Peppol. Add a rule with delivery "Peppol" for any other buyer country that uses Peppol.

5. Buyer Peppol IDs

• At checkout (payment step): "Peppol ID (optional)" is shown for the countries your rules send over Peppol, with the note "Leave empty if you do not know it; we use your VAT ID." The value is checked on the server: scheme:identifier, for example 0208:0123456789.
• On the order page: the E-Invoicing box edits the buyer's Peppol ID and VAT ID. Regenerate documents that were not sent yet after a change.
• From the VAT ID when no Peppol ID was entered: Belgium uses 0208 plus the enterprise number, Denmark 0184, Sweden 0007, Norway 0192, other EU countries the VAT scheme of the Peppol code list (for example 9944 for the Netherlands, 9930 for Germany).
• German public bodies (with E-Invoicing: Germany): the Leitweg-ID is used as Peppol ID with scheme 0204.

6. Checks before sending

Every document is checked before it can be sent: EN 16931 business rules, the XML schema, a check that the total equals Magento's total, and the Peppol checks PEPPOL-EN16931-R003 (buyer reference or purchase order reference), R010 (buyer Peppol ID), R020 (your Peppol ID), the electronic address scheme and the Belgian enterprise number check for 0208. Before sending, the channel also checks that the document is UBL, that both Peppol IDs are present and, if switched on, that the buyer is registered on the Peppol network for this document type. In our tests the documents were validated with the official artefacts: the OpenPeppol BIS Billing 3.0 schematron, the CEN EN 16931 UBL rules 1.3.16 and 1.3.17, and the Peppol validation service (VESID 2026.5).

7. Daily use

E-Invoices grid (CommerceGears > E-Invoicing > E-Invoices): format, delivery, status and problem of every document, with search, filters and the mass actions Generate / Regenerate (Not Sent Yet), Send, Check Delivery Status, Cancel (Not Sent Yet) and Download Files (ZIP).

Document page: status and network status, the buyer's electronic address, the network ID, SHA-256 checksums, validation and the audit trail with the provider's API calls (secrets masked). Actions depending on the state: Send, Check Status, Send by E-mail Instead, Regenerate, Validate Again, Cancel.

Statuses: Ready (valid, waiting to be sent), Sent, Delivered, Rejected, Failed. With e-invoice.be and Recommand, cron checks the status of sent documents. Storecove reports by webhook to your Storecove account, which the module does not read; check those documents in the Storecove dashboard.

Problems: network failures are retried with growing pauses (up to 6 attempts by default). A delivered document is never sent twice. When a provider does not answer after the document was transmitted, the document is marked "Failed" with a note instead of being sent again automatically: check it at the provider before you send it again. A buyer that is not registered on Peppol, or does not receive the document type, stops the document with a message; correct the Peppol ID or click Send by E-mail Instead.

Order page: the E-Invoicing box lists the order's documents with their files, creates a document by hand in any installed format and delivery, and edits the buyer details.

Customer account: logged-in customers download the Peppol BIS XML under Electronic Invoices on the Invoices and Refunds tabs of their orders, on Luma and Hyvä.

8. CLI

bin/magento commercegears:einvoice:peppol-lookup 0208:0123456789 [--test]   # Peppol network (SML/SMP) and Directory
bin/magento commercegears:einvoice:test-connection peppol                   # provider login with the saved settings
bin/magento commercegears:einvoice:process                                  # what the cron does
bin/magento commercegears:einvoice:send 42 [--status]                       # send one document or check its status
bin/magento commercegears:einvoice:validate 42                              # checksum and XML schema of a document

9. Permissions (ACL)

Under System > Permissions > User Roles, CommerceGears > E-Invoicing: View E-Invoices and Download Files, Generate, Send and Cancel E-Invoices, Edit Buyer E-Invoice Details on Orders and Settings (also for the E-Invoicing: Peppol section).

10. Troubleshooting

• Documents stay "Ready": no provider or API key is set, or Send Automatically is No. Set the provider and send them from the grid or wait for cron.
• "The buyer has no Peppol ID": enter it in the E-Invoicing box on the order page and regenerate, or send by e-mail.
• "... is not registered on the Peppol network": check the Peppol ID with the buyer (peppol-lookup shows what the network knows), or send by e-mail.
• "... does not receive Peppol BIS Billing 3.0 invoices": the buyer is on Peppol for other document types only. Ask the buyer which format they receive, or send by e-mail.
• "... is not listed in the Peppol Directory": the network lookup could not be reached from your server (DNS or firewall) and the buyer has no Directory entry. Allow DNS and HTTP(S) to the Peppol SML/SMPs, or switch Check Buyer on Peppol off.
• "Your Peppol ID is missing in the seller settings": fill in the Electronic Address Scheme and ID in Seller (Your Company).
• Test Connection fails: check that the environment matches the key (sandbox key with Sandbox / Test).

11. Uninstall

composer remove commercegears/module-e-invoicing-peppol
bin/magento setup:upgrade

Documents already created stay in E-Invoicing Core. Keep them for the legal retention period: the module never deletes documents or files.