Preparation
Before you start, make sure you have:
- PortaSwitch MR132-0 or later.
- An active Storecove account with access to the Storecove portal. Complete the Storecove onboarding, including Peppol registration, for each country where you send eInvoices.
- An Add-on Mart account with a trial or paid subscription to the eInvoicing (Storecove) module.
- A public DNS name for the module instance that points to the Add-on Mart cluster where the instance is deployed. Create a CNAME record (or an A record) for this name as described in Add-on Mart addresses by region. Both PortaBilling and Storecove connect to the module over HTTPS using this name.
TLS certificates for this domain can be generated automatically by PortaOne using Let’s Encrypt certification authority (CA). Optionally, you can contact your trusted CA to order a TLS certificate for your domain.
- The Peppol ID (Peppol ID scheme and participant ID) of each customer who will receive eInvoices.
Configuration overview
- Set up the Storecove account
- Create a new API user in PortaBilling with an access token
- Configure and deploy the module in the Add-on Mart management portal
- Register the delivery callback in Storecove
- Enable eInvoicing on the Configuration server web interface
- Specify your company information in PortaBilling
- Create the ESPF event handler
- Enable eInvoicing for a customer class
- Configure a customer
When you finish, check that eInvoicing works with a test customer.
Step 1. Set up the Storecove account
Perform these steps in the Storecove portal. Save the API key and legal entity ID values you get here – you will need them to configure the module in step 3.
- Create an API key for the Access Point as a Service. Copy the key right away, as Storecove shows it only once.

- Create a legal entity for your company that acts as the sender of eInvoices. Specify your company’s registered name and address and add your Peppol identifier(s), such as your GLN or national registration number. Note the numeric ID of the legal entity.

- If your company is registered for VAT, mark the legal entity as tax registered and add your VAT number as a Peppol identifier. Select your country’s VAT scheme, for example, BE:VAT for Belgium, and enter your VAT number starting with the two-letter country code, for example, BE0123456749. You will enter the same VAT number as the Tax ID in PortaBilling in step 6. Storecove rejects eInvoices if the legal entity isn’t marked as tax registered or has no VAT number, or if the VAT numbers in Storecove and PortaBilling don’t match.
For detailed instructions, refer to the Storecove documentation.
Step 2. Create a new API user in PortaBilling with an access token
The module requires API user credentials to retrieve the data from PortaBilling via the API. Creating a dedicated admin user for this purpose is recommended.
To create a new user, log in to PortaBilling and perform the following steps:
- Navigate to My company > Access control > Users.
- Click +Add and fill in the user details:
- Login – type the username that will be used by the module for connecting to the PortaBilling API;
- Email – type in the email address of the admin (for receiving alerts or password recoveries for the user);
- Password – type a long and strong password for this user;
- Role – select a role for this user.

Ensure the selected role has no restrictions on the entities that require data access. It’s recommended to create a dedicated admin role with the following permissions:
- Customer – “Read”
- Company info – “Read”
- Invoice – “Modify”
- Click Save.
- Open the user record, navigate to the Web interface panel, enable the API token access, and generate an API token.

Copy the login and the API token. You will enter them in the module configuration in step 3.
Step 3. Configure and deploy the module in the Add-on Mart management portal
Log in to the Add-on Mart management portal, open My modules, locate your eInvoicing (Storecove) subscription, and click Configure.

On the Configuration page that opens, fill in the details:
General settings
Instance location – select the Add-on Mart cluster that the module domain points to (see Preparation).
Version to deploy – choose a module version. The following options are available:
- Deploy the latest (recommended) – select if you want to deploy the latest version.
- Select from the full list – select if you want to deploy another version.

Choose domain configuration
- Module domain – specify the public DNS name of the module instance (see Preparation).
- Generate certificates – select this checkbox so that the Add-on Mart issues the TLS certificate for the module domain automatically. Alternatively, clear the checkbox and upload your custom certificate and the private RSA key for your domain.

PortaBilling
Fill in the parameters that the module needs to connect to the PortaBilling API:
- PortaBilling API URL – specify the URL of the PortaBilling REST API, e.g., https://<pb-web-host>/rest. Use the same host as the PortaBilling admin web interface. Add the :8443 port only if the API is available on that port.
- API user login – specify the login of the API user created in step 2.
- API user token – specify the API token generated in step 2.

ESPF webhook
Fill in the credentials that PortaBilling uses to send invoice events to the module. The module rejects events without these credentials.
- Webhook username – specify any username. You will enter the same value in the BasicAuth.User field of the event handler in step 7.
- Webhook password – specify a strong password. You will enter the same value in the BasicAuth.Key field of the event handler in step 7.

Storecove
- API key – specify the Storecove API key from step 1.
- Legal entity ID – specify the ID of the sender legal entity from step 1.
- Delivery callback token – specify a secret value that is hard to guess, as you would for a strong password. Storecove sends this value with every delivery result, so the module can verify that the result really comes from Storecove. You will enter the same value as the x-callback-token header value of the Storecove webhook in step 4.

eInvoicing
Specify why your VAT-exempt invoices don’t include VAT. The module adds this reason only to VAT-exempt invoices (category E). If you issue only standard VAT invoices, leave both fields empty.
- Tax exemption reason code – specify the VATEX code of the exemption, e.g., VATEX-EU-132 for exemptions under Article 132 of Directive 2006/112/EC. See the full list of codes in the Peppol VATEX code list. Specify only a code that describes an exemption. If you specify a code of another kind (e.g., VATEX-EU-AE), the exempt invoices fail.
- Tax exemption reason text – specify the description of the exemption, e.g., “Exempt from VAT (Article 132 of Directive 2006/112/EC)”.
The EN 16931 standard accepts either the code or the text. We recommend that you specify both: the code is used for automatic validation and the text is for the person who reads the invoice.

Deployment
Click Deploy (or Save for later to deploy it later) and wait until the deployment status is Success.
Then open the deployment details and copy the two URLs listed under Post-deployment artifacts:
- ESPF webhook URL (https://<module-domain>/webhooks/invoice) – you will need it in step 7.
- Delivery callback URL (https://<module-domain>/webhooks/delivery_status) – you will need it in step 4.

Step 4. Register the delivery callback in Storecove
Storecove reports the delivery result to the module using a webhook. If you don’t set it up, eInvoices stay in the Submitted status even after Storecove delivers them and are marked as failed when the delivery timeout expires.
In the Storecove portal, create and enable a webhook with the following settings:
- Event to notify – select Document sending result (document_submission).
- Webhook mode – select Push and enable the webhook.
- URL – enter the delivery callback URL from step 3 (in the format https://<module-domain>/webhooks/delivery_status).
- Authentication – select HTTP Header, specify x-callback-token as the header name, and enter the Delivery callback token from step 3 as the header value.


Step 5. Enable eInvoicing on the Configuration server web interface
Log in to the Configuration server web interface and perform the following steps:
- Navigate to Web Cluster > Global > EInvoice and set Enabled to Yes.
- Optionally, adjust DeliveryTimeoutHours (48 by default). This is how long an eInvoice can remain in the Submitted status before it is marked as Delivery failed and the administrator is notified.

- Verify and apply the configuration.
Step 6. Specify your company information in PortaBilling
Log in to the PortaBilling web interface, open My company > Company info, and perform the following steps:
- Go to the Address information panel and make sure your company name, country, address, city, and postal code are specified. The country is the seller country on the eInvoice. It also determines which VAT rates Storecove accepts on the eInvoice.

- If your company is registered for VAT, go to the Invoicing and taxation panel and make sure your VAT number with the country prefix is specified in the Tax ID field (e.g., BE0123456789). This must be the same VAT number that you added to the Storecove legal entity in step 1.

- If this is the first Add-on Mart module you set up, go to the Add-on Mart panel and enter the PortaSwitch Credentials from the Add-on Mart management portal. For details, see Connect PortaSwitch to Add-on Mart. Skip this step if you have already done this for another module.

- Click Save.
Step 7. Create the ESPF event handler
PortaBilling notifies the module about new, changed, and voided invoices via the External System Provisioning Framework (ESPF). To send these events to the module, create an EventSender handler.
- In PortaBilling, navigate to Infrastructure > Event handlers and add click + Event handler.
- Fill in the handler details:
- Name – type a descriptive name for the handler.
- Type – select EventSender.
- Enabled – leave the checkbox selected so that the handler starts sending events once it’s configured.
- Events version – select Events v.1. The module doesn’t accept v.2 events.
- AuthMethod – select Basic.
- BasicAuth.Key – enter the Webhook password from the module configuration in step 3 – ESPF webhook.
- BasicAuth.User – enter the Webhook username from the module configuration in step 3 – ESPF webhook.
- URL – enter the ESPF webhook URL from the deployment details in step 3 – Deployment (e.g., https://<module-domain>/webhooks/invoice).
- Leave the other parameters at their default values.

- On the Event subscriptions tab, enable these four events:
- Invoice/New
- Invoice/Status/Changed
- Invoice/Voided
- Invoice/EInvoice/RetryRequested

- Click Save.
Step 8. Enable eInvoicing for a customer class
You can enable eInvoicing for a customer class or for an individual customer. If you enable it for a customer class, it applies to all customers in that class whose eInvoicing setting is As defined by the customer class, which is the default. To make an exception, change the setting for a specific customer in step 9. For example, you can enable eInvoicing for a single customer whose class doesn’t use it, or disable it for a customer in a class that does.
- Open the customer class and go to Finances > Regular invoices.
- Make sure an invoice template is selected in the Invoice template field. PortaBilling doesn’t generate invoices without a template, even for customers who receive only eInvoices. The template defines only the PDF invoice layout; the module builds the eInvoice from the invoice data.
- Turn on Generate an eInvoice. If the option is unavailable and has an orange Add-on Mart icon next to it, PortaBilling can’t connect to the module. Check the Add-on Mart credentials from step 6.
- Optionally, set Send the PDF invoice via email. When eInvoicing is enabled, this option works as follows:
- Never – the customer receives an email with the eInvoice XML file only.
- Automatically or After review and approval by admin – the customer receives an email with both the PDF invoice and the eInvoice XML file.
Whichever option you select, PortaBilling sends the email only after the eInvoice is delivered, so the customer receives the final document.

- Click Save.
Step 9. Configure a customer
For each customer who receives eInvoices, you need to specify their own Peppol ID and a complete company address. If your company is registered for VAT, the customer also needs VAT taxation settings.
Open a specific customer and configure the following:
- Go to General info > Basic info and specify the customer’s company name, street, city, postal code, and country. These fields are mandatory – Storecove rejects eInvoices without a complete buyer address.

- Go to the Finances > Financial info tab:
- Generate an eInvoice – select Enabled or As defined by the customer class to use the setting from step 8.
- The Peppol ID scheme – select the type of identifier under which the customer is registered on Peppol (e.g., BE:EN for a Belgian enterprise number or BE:VAT for a Belgian VAT number).
- The Peppol participant ID – specify the customer’s identifier in the selected scheme.
- If your company is registered for VAT, configure taxation for the customer in the Taxation section on the same tab:
- Taxation plug-in – select the taxation plug-in (e.g., Fixed VAT Rate).
- Tax ID – specify the customer’s VAT number with the country prefix.
- Taxes included into rates/fees – make sure this option is turned off. eInvoicing doesn’t support tax-inclusive prices.
- Exempt from – select Default to use the customer class setting, No if the customer pays VAT, or Yes if the customer is exempt from VAT. For exempt customers, the eInvoice includes the tax exemption reason from step 3 – eInvoicing.
- VAT % – specify the VAT rate you charge the customer.
- Click Save.

Check that eInvoicing works
- Open a test customer configured as described in step 9 and add a manual charge (Balance adjustments > Manual charge).
- Wait about 30 seconds for PortaBilling to calculate taxes for the charge, then generate an invoice on demand.
- On the Issued invoices tab, check the invoice’s eInvoice status. Within a minute, the status changes from Pending to Submitted and then to Delivered once Storecove has delivered it over Peppol.
The eInvoice column is hidden by default – to display it, click Settings on the title bar, click Customize columns, and select the eInvoice checkbox.
- Once the eInvoice is delivered, use the Download the eInvoice action to get the final XML document.

In the Storecove portal, the eInvoice appears in Invoices Sent with a delivery mark, and Settings > Webhook History shows the callback to the module with the 200 OK response.
eInvoice statuses
To see the status details, such as the time of the last status change and the reason for a failure, hover over the status icon in the eInvoice column.
| Status | Meaning | What to do |
| Not applicable | eInvoicing isn’t enabled for the customer. | – |
| Pending | The module has received the event and is creating the eInvoice. | Wait. If the status doesn’t change, the event didn’t reach the module. Check that the event handler from step 7 is enabled, subscribed to the four events, and uses the URL and credentials from step 3. |
| Submitted | Storecove has accepted the eInvoice and is delivering it. | Wait for the delivery result. If the status doesn’t change, check the webhook history in the Storecove portal: the webhook from step 4 must be enabled, and the module must respond with 200 OK. |
| Delivered | The eInvoice has been delivered. The XML file is available for download. | – |
| Generation failed | The eInvoice couldn’t be created or was rejected by Storecove. | Correct the data mentioned in the failure reason (e.g., add a postal code to the customer’s address) and use the Retry the eInvoice generation action.
If the reason is BR-O-02, the customer has no taxation plug-in enabled while your company has a Tax ID: select a VAT taxation plug-in for the customer, e.g., Fixed VAT Rate. |
| Delivery failed | Storecove reported a delivery failure or didn’t report the delivery result within the delivery timeout (48 hours by default). | Check the customer’s Peppol ID and the Storecove webhook, then use the Retry the eInvoice generation action. |
| Cancelled | The invoice was voided before its eInvoice was successfully sent, so no eInvoice was delivered to the customer. | – |
| Voided | The invoice was voided after the eInvoice had been submitted. | Agree with the customer on how to handle the original eInvoice: it can’t be withdrawn. If PortaBilling generates a replacement invoice, it’s sent as a separate eInvoice. |