B2Brouter plugin for WooCommerce

B2Brouter for WooCommerce is a plugin that automatically generates and sends your WooCommerce store's e-invoices through B2Brouter. Every order gets its invoice, in the format each country requires, without you having to do anything.

• Automatic compliance. Invoices comply with each country's e-invoicing regulations.
• No manual work. Invoices are generated automatically for every order, or whenever you decide.
• Standard formats. Invoices structured in UBL, CII and other formats.
• International sales. Works for B2B and B2C sales, including outside your country.
• Built into WooCommerce. It doesn't change the way you run your store.

B2Brouter for WooCommerce WordPress Free plugin in the official WordPress repository.

---

Requirements

Before installing the B2Brouter plugin, make sure you have:

• WordPress 5.8 or higher
• WooCommerce 5.0 or higher, installed and active
• PHP 7.4 or higher
• A B2Brouter account with an active eDocExchange subscription

If you don't have WooCommerce installed yet, go to Plugins → Add New, search for "WooCommerce", install it and activate it before continuing.

---

Installation

From the official WordPress repository Recommended option

1. In the WordPress admin, go to Plugins → Add New.
2. Search for "B2Brouter for WooCommerce".
3. Click Install Now and then Activate.

Manual download Alternatives

If you prefer to install it manually, you can download the ZIP file from:

• The official WordPress repository
• The GitHub releases page

Once you have the ZIP, go to Plugins → Add New → Upload Plugin, select the file, and click Install Now and Activate.

Once activated, the plugin's welcome page will appear with the initial instructions. In the sidebar menu you will see the new Invoices section.

---

Testing the plugin in a staging environment

Before connecting the plugin to your real store, test it on a copy of your WordPress site (a WordPress staging site) connected to the B2Brouter sandbox. This lets you check numbering, taxes and PDFs without generating real invoices. Step 1 explains how to create this copy.

Important: do not use the sandbox on your production store

The B2Brouter sandbox generates documents marked as "Not valid". If you configure the plugin with a sandbox key (test_…) on your real WooCommerce store:

• Your real customers' orders would generate invoices with no legal validity.
• Status changes (invoice issued, registered, etc.) would not reach your WooCommerce store, because production and sandbox webhooks do not communicate with each other.
• You would lose numbering traceability and quota.

The sandbox is intended exclusively for testing environments. Before configuring the plugin against your real account, we recommend testing it in a staging environment.

Why it is worth testing first

Before connecting the plugin to your production store, it is worth verifying in a test environment:

• That invoice numbering is applied correctly and does not conflict with any other tool.
• That taxes (including intra-community reverse charge) are calculated as expected.
• That the VAT number field is collected at checkout and propagated to the invoice.
• That PDFs are generated and can be downloaded from "My Account".
• That emails to the customer work with the correct text and attachments.

All of this can be validated end-to-end in the sandbox without consuming quota, without sending anything via Peppol, and without generating real accounting entries.

Step 1: Create a staging environment for your WordPress site

You have two options:

Option A: hosting staging (recommended if available)

Most managed WordPress providers include a one-click staging system from their control panel:

• SiteGround — Site Tools → Dev → WordPress Staging
• Kinsta — Sites → Create Staging Environment
• WP Engine — Add Staging Environment
• Cloudways — Application → Clone App / Create Staging
• Hostinger — Hosting → Manage → Create staging

Check your hosting panel before installing anything — it is the cleanest way to have a staging environment.

Option B: WP STAGING plugin

If your hosting does not offer staging or you do not have access to it, the free WP STAGING plugin (wordpress.org/plugins/wp-staging) creates a clone of your store in a subdirectory (e.g., yourstore.com/staging) with a single click. The clone has its own login and database and does not touch any data from the real store.

💡 Never mix a B2Brouter sandbox with a production store: always confirm that the URL where you configure the plugin ends in /staging or a test domain before entering any key.

Step 2: Get a sandbox API key

1. Log in to B2Brouter with your usual account.
2. Go to Developers → Sandboxes and open (or create) a sandbox.
3. Inside the sandbox, go to API Keys and generate a new key. It will start with the prefix test_.
4. Copy the key — you will need it in the next step.

For more details about what the sandbox includes and does not include, consult the sandbox technical documentation.

Step 3: Configure the plugin on staging

On your staging WordPress (not on production):

1. Install and activate the B2Brouter plugin as described in the "Requirements" and "Installation" sections.
2. In the plugin settings, enter the test_… key you generated.
3. Configure the rest of the parameters (numbering pattern, taxes, PDFs, etc.) as you would in production — you can return to the "Initial configuration" section for details.

Step 4: Configure sandbox webhooks

🚧 Webhooks in the sandbox environment are coming soon.

Step 5: Pre-production checklist

Place a test order on staging and confirm:

• An invoice is generated in the B2Brouter sandbox when the order is completed.
• The invoice number follows the pattern you configured.
• Taxes are correct, including reverse charge if you make intra-community B2B sales.
• If the customer enters a VAT number, it is recorded in the invoice.
• The PDF downloads correctly from "My Account" (it will carry the "Not valid" mark — this is normal in the sandbox).
• Emails fire with the correct attachments.

Step 6: Go to production

When everything works on staging:

1. On your production WordPress, install the plugin (if you have not done so yet) and configure it from scratch with the prod_… key from your real account.
2. Configure the webhooks on your B2Brouter production account, pointing to the production WordPress URL.
3. Do not migrate data from staging to production — test invoices (those marked as "Not valid") must stay in the sandbox only.
4. Place a small real test order to confirm that the entire flow also works in production.

---

Initial configuration

Step 1: Obtain B2Brouter credentials

1. Register at app.b2brouter.net.
2. Purchase an eDocExchange subscription.
3. Go to Developers → API Keys in the B2Brouter dashboard.
4. Copy the API key and store it securely.

You are configuring the production environment

If you have not tested the plugin yet, we recommend doing so first in a staging environment with a sandbox key. See the "Testing the plugin in a staging environment" section.

Step 2: Configure the plugin

1. Access the settings:

   • In WordPress, go to Invoices → Settings.

2. Enter the API key:

   • Paste your B2Brouter API key.
   • Click Validate Key.
   • If the API key is correct, the plugin will display your account information.

3. Configure the generation mode:

   • Automatic: The plugin automatically generates the invoice when an order moves to the Completed status. This is the recommended option if you want to ensure that all orders have an associated invoice.
   • Manual: The plugin does not generate the invoice automatically. The invoice can be generated manually from each order's detail page and, once the order is in Completed status, the customer can also generate it from their account page. This is the recommended option if you prefer the customer to decide when to generate the invoice.

Step 3: Configure invoice numbering

1. Series codes:

   • Invoice series code: Prefix for regular invoices (e.g., "INV", "FAC")
   • Credit note series code: Prefix for credit notes (e.g., "CN", "NC")

2. Numbering pattern: there are four options to define how invoices are numbered.

   a) Automatic Recommended

   • B2Brouter generates sequential numbers automatically.
   • No need to manage counters.

   b) WooCommerce order number:

   • Uses the native WooCommerce order number.
   • Example: If the order is #1234, the invoice will be INV-1234.

   c) Sequential:

   • The plugin maintains an independent counter.
   • Generates numbers like INV-00001, INV-00002, INV-00003.

   d) Custom pattern:

   • Define your own format using placeholders:
     • {order_id}: Order ID
     • {order_number}: WooCommerce order number
     • {year}: Current year (YYYY)
     • {month}: Current month (MM)
     • {day}: Current day (DD)

   Custom pattern examples:

   • INV-{year}-{order_id} → INV-2025-123
   • {year}/{month}/{order_number} → 2025/12/1234
   • INV{year}{month}{day}-{order_id} → INV20251211-123

Step 4: Configure PDFs

1. Automatic PDF cache:

   • Enable this option to download and save PDFs on the server, inside the wp-content/uploads/b2brouter-Invoices/ folder.
   • Improves response time for customer downloads.
   • Reduces calls to the B2Brouter API.

2. Automatic cleanup:

   • Enable scheduled cleanup to delete PDFs that exceed the number of days defined in the retention period.
   • Configure the retention period (default: 90 days).
   • Cleanup runs daily via WordPress cron.

3. Attach PDFs to emails:

   • Attach to completed order email: Includes the PDF when the confirmation email is sent.
   • Attach to customer invoice email: Includes the PDF in WooCommerce invoice emails.
   • Attach to refund email: Includes the credit note in refund emails.

---

Invoice generation mode

Automatic generation

If you have enabled Automatic mode:

1. The customer completes a purchase.
2. Process the order and mark it as Completed.
3. The plugin:
   • Automatically generates the invoice in B2Brouter.
   • Saves the invoice metadata (ID, number, date).
   • Adds a note to the order.
   • Generates and saves the PDF (if enabled).
   • Sends the email with the PDF attached (if configured).

Manual generation - individual order

If you have enabled Manual mode and need to generate an invoice:

1. Go to WooCommerce → Orders.
2. Open the order you want to invoice.
3. Locate the B2Brouter Invoice meta box.
4. Click the Generate Invoice button.
5. The metabox will display the status and main details of the invoice.
6. You can download the PDF directly from here.

Manual generation - bulk actions

To process multiple orders at once:

1. Go to WooCommerce → Orders.
2. Select the completed orders you want to invoice.
3. In the bulk actions dropdown menu, choose Generate B2Brouter Invoices.
4. Click Apply.
5. You will see a message with the result for each order:
   • Successfully generated invoices
   • Invoices that already existed
   • Errors during generation

Generating credit notes

Credit notes are generated for WooCommerce refunds:

1. Open the order in WooCommerce → Orders.
2. In the 'Item' meta box, click Refund (the order must have an invoice).
3. Enter the refund amount, which can be full or partial.
4. Confirm the refund.
5. The credit note is automatically generated in the country-specific format (e.g., Spanish corrective invoices, facturas rectificativas).

---

Tax configuration

The plugin reads the WooCommerce tax configuration and automatically converts it into Peppol tax categories.

Peppol tax categories

• S (Standard rate): applied when taxes exist.
• E (Exempt from tax): taxable products with a 0% rate.
• Z (Zero-rated goods): products with an explicit zero tax class.
• NS (Not subject to tax): non-taxable products.
• AE (VAT reverse charge): automatically detected for intra-EU B2B transactions.

Tax configuration in WooCommerce

1. Enable tax calculation:

   • Go to WooCommerce → Settings → General.
   • In the Tax and coupon section, enable "Enable tax rates and calculations".

2. Configure taxes

   • Once taxes are enabled, go to WooCommerce → Settings → Tax. From this section you can configure the different tax rates:

   • Configure standard rates:

     • Click the Standard Rates tab.
     • Add your rates by country:
       • Country code
       • Tax percentage
       • Tax name (VAT, etc.)
       • Whether it applies to shipping

   • Configure zero rate:

     • Click the Zero Rate tab.
     • Add your rates by country:
       • Country code
       • Tax name (VAT, etc.)
       • Whether it applies to shipping

   • Configure reduced rate:

     • Click the Reduced Rate tab.
     • Add your rates by country:
       • Country code
       • Tax percentage
       • Tax name (VAT, etc.)
       • Whether it applies to shipping

Intra-EU reverse charge

The plugin automatically detects when reverse charge applies:

Conditions:

• The customer provides a valid VAT number.
• The customer's country is different from the merchant's country.
• Both countries are EU member states (27 states).

What the plugin does:

• Marks the transaction as reverse charge (AE category).
• Generates the invoice without taxes applied to the customer.
• Indicates that the customer must declare the taxes in their own country.

---

VAT number collection

VAT number field configuration

The plugin automatically adds a VAT number field to the WooCommerce checkout. Compatible with:

• Block-based checkout (WooCommerce 8.6+)
• Classic shortcode-based checkout

How it works

1. At checkout:

   • The "NIF / VAT Number" field appears in the contact information section.
   • It is optional by default.
   • The customer can enter their VAT number for B2B/B2C invoices.

2. Storage:

   • The VAT number is saved as _billing_tin in the order metadata box.
   • It is also saved to the customer's profile for reuse.

3. Invoicing:

   • If the customer provides a VAT number, a standard invoice (IssuedInvoice) is generated.
   • If there is no VAT number, a simplified invoice (IssuedSimplifiedInvoice) is generated.
   • For intra-EU transactions with a VAT number, reverse charge is applied.

VAT number validation

Currently the plugin does not validate the VAT number format. Validation can be added via:

• Third-party validation plugins
• Custom validation with WooCommerce hooks
• Validation through the B2Brouter API

---

Webhook configuration

Why use webhooks?

• Instant updates: Invoice status appears immediately in the WordPress admin.
• Less load: Reduces API calls.
• More reliable: With hourly fallback check.

Step-by-step configuration

Step 1: Get the URL from the WordPress admin panel

1. Go to Invoices → Settings.
2. Scroll down to "Webhook Configuration".
3. Enable "Enable Webhooks".
4. Copy the Webhook URL from the read-only field.
   • It looks like: https://yoursite.com/wp-json/b2brouter/v1/webhook
5. Save the settings.

Step 2: Create the endpoint in the B2Brouter dashboard

1. Log in to app.b2brouter.net.
2. Go to the Developers tab.
3. Click on Webhooks in the main menu.
4. Click "Add webhook".
5. Enter a description, e.g., "WooCommerce Store".
6. Paste the Webhook URL copied from WordPress.
7. Select the events to send. Recommended: select all.
8. Save the endpoint and copy the signing key of the generated webhook.

Step 3: Complete the configuration in the WordPress admin panel

1. Return to Invoices → Settings → Webhook Configuration.
2. Paste the signing key from B2Brouter.
3. Leave the "Enable Security Check" option enabled.
4. Click "Save Settings".

Verification

To verify that webhooks are working correctly:

1. Generate a test invoice.
2. The status should appear in less than 1 second.
3. If there are issues:
   • Verify that the Webhook URL matches exactly.
   • Make sure the Secret is pasted correctly (no extra spaces).
   • Check that your WordPress site is accessible from the Internet.

Webhook security

• All requests are cryptographically signed with HMAC-SHA256.
• Requests with invalid signatures are rejected.
• 5-minute timestamp validation to prevent replay attacks.
• The secret is stored securely in WordPress options.

---

PDF management

Server storage

When you enable "Automatic PDF Cache":

1. Location: wp-content/uploads/b2brouter-Invoices/
2. Structure:

   b2brouter-Invoices/
   ├── 2025/
   │   ├── 01/
   │   │   ├── invoice-123.pdf
   │   │   └── credit-note-124.pdf
   │   └── 02/
   │       └── invoice-125.pdf

Automatic cleanup

The plugin includes a scheduled task to clean up old PDFs:

1. Configuration:

   • Enable the "Automatic cleanup" checkbox.
   • Set the retention period (default: 90 days).

2. How it works:

   • Runs daily via WordPress cron.
   • Deletes files older than the retention period.
   • Maintains the folder structure.
   • Logs cleanups to the WordPress log.

3. Disabling cleanup:

   • If you disable cleanup, PDFs are kept indefinitely.
   • You will need to manage disk space manually.

Manual invoice download from the WordPress admin

1. Go to WooCommerce → Orders and select the order whose invoice you want to download.
2. From the order's "B2Brouter Invoice" metabox, click Download PDF.
3. If the PDF is cached, it downloads immediately.
4. If not, the plugin:
   • Requests the PDF from B2Brouter.
   • Caches it (if enabled).
   • Downloads it to your browser.

---

Customer experience

Invoice downloads

Customers can access their invoices in several ways:

1. From their account → Orders:

   • The order list is displayed.
     • If the invoice has already been generated, the Download Invoice button will appear in the Actions column of the order list. Click to download the invoice.
     • If the invoice has not been generated, the Generate Invoice button will appear in the Actions column of the order list. Click to generate the invoice. Once generated, the button will change to Download Invoice. Click to download the invoice.

2. From their account → Orders → Order:

   • From the order list, in the Actions column of an order, click View on the order.
   • On the order details page, you will find:
     • Download Invoice button.
     • Download Credit Note button (if applicable).

3. From email:

   • If you have enabled "Attach to emails".
   • The PDF is included as an attachment in the confirmation email.

4. Customer-generated invoices (manual mode):

   • If the mode is Manual, customers can generate invoices themselves.
   • On the order details page, they will see a Generate Invoice button.
   • After clicking, the page refreshes and the PDF is available.

Security

The plugin implements several security measures:

1. Ownership verification: Customers can only access their own invoices.
2. Status validation: Invoices can only be generated for completed orders.
3. CSRF protection: All actions use WordPress nonces.
4. Mode validation: Customer-side generation only works in Manual mode.

---

Best practices

Test environment

• Start with the sandbox and your WordPress staging site, as explained in "Testing the plugin in a staging environment".
• Test the entire invoicing flow before going to production.
• Generate test orders with different configurations (with/without VAT number, various countries, etc.).

Backups

• Perform regular backups of your WordPress database.
• Include the wp-content/uploads/b2brouter-Invoices/ directory in your backups.
• Test backup restoration periodically.

Monitoring

• Regularly review the B2Brouter → Invoices page to check the status.
• Set up notifications for invoice generation errors.
• Check the WordPress logs periodically.

Updates

• Keep the plugin updated to the latest version.
• Review the changelog before updating.
• Test updates in the staging environment first.

Performance

• Enable "Auto-save PDFs" to improve response time.
• Configure automatic cleanup to manage disk space.
• Use webhooks for real-time status updates.

---

Legal requirements

Tax compliance

The plugin helps with tax compliance, but:

• Responsibility: The merchant is responsible for tax compliance.
• Configuration: Make sure the tax configuration is correct for your country.
• Advice: Consult with a tax advisor for the specific requirements of your country.

Data protection (GDPR)

The plugin processes personal data:

• Legal basis: Necessary for compliance with legal obligations.
• Data processed: Name, address, VAT number, order information.
• Storage: Data is saved in WordPress and sent to B2Brouter.
• Retention: Configure the retention period according to your legal requirements.

Update your privacy policy to include:

• The use of B2Brouter for invoice generation.
• The data that is sent to B2Brouter.
• How customers can exercise their rights.

---

Common issues

These are the most common issues when setting up and using the plugin, with the likely cause and how to fix them. If your case isn't listed, or you want more detail about the error, enable debug mode first.

Enable debug mode

1. Add these lines to your wp-config.php:

   define( 'WP_DEBUG', true );
   define( 'WP_DEBUG_LOG', true );
   define( 'WP_DEBUG_DISPLAY', false );

2. Errors will be logged to wp-content/debug.log.

3. Search for entries containing "B2Brouter" to see plugin errors.

1. API key validation error

Symptoms: Message "Error validating the API key"

Solutions:

• Verify that the API key is correct.
• Make sure your eDocExchange subscription is active.
• Check that your server can connect to B2Brouter (not blocked by a firewall).

2. Invoices are not generated automatically

Symptoms: Orders are completed but no invoices are generated.

Solutions:

• Verify that the mode is set to Automatic in the settings.
• Check that the order status is Completed.
• Review the order notes for any errors.
• Check the WordPress logs for detailed errors.

3. PDFs are not attached to emails

Symptoms: Emails are sent but without the PDF attachment

Solutions:

• Verify that "Auto-save PDFs" is enabled.
• Check that "Attach to emails" is enabled.
• Make sure the invoice has been generated before the email is sent.
• Review the SMTP server logs for any sending errors.

4. Webhooks are not working

Symptoms: Invoice status is not updated immediately

Solutions:

• Verify that the Webhook URL matches exactly.
• Check that the Webhook Secret is correct.
• Make sure your site is accessible from the Internet (webhooks do not work on localhost without tunneling).
• Review the WordPress logs to see if requests are arriving.
• Check that there are no SSL errors on your site's certificate.

5. Error "Could not generate the PDF"

Symptoms: The invoice is created but the PDF cannot be downloaded

Solutions:

• Check that the wp-content/uploads/ directory has write permissions.
• Review the invoice status in B2Brouter (it may not have been processed yet).
• Try regenerating the PDF forcefully (Shift + click).
• Verify that the B2Brouter API is operational.

6. PDFs carry the "Not valid" watermark or webhooks are not arriving

Symptoms: Generated invoices download with a watermark that reads "Not valid", and/or the order status in WooCommerce is not updated after payment is processed.

Most likely cause: you are using a sandbox API key (starts with test_) instead of a production key (starts with prod_), or your webhooks are configured in the sandbox instead of the real account.

Solutions:

1. Check the API key prefix in the plugin settings:
   • test_… → you are in the sandbox. Documents have no legal validity and production webhooks will not arrive.
   • prod_… → you are in production. This is what you want on the real store.
2. If you have confirmed the key is prod_… but webhooks are still not arriving, go to your B2Brouter production account (not the sandbox) and review the webhook configuration.
3. If you are intentionally using the test_… key for testing, make sure you are doing so in a staging environment and not on the real store. See the "Testing the plugin in a staging environment" section.

7. Incorrect tax categories

Symptoms: Tax categories are not correct on the invoices

Solutions:

• Review the tax configuration in WooCommerce → Settings → Tax.
• Make sure the tax classes are configured correctly.
• Verify that products have the correct tax class assigned.
• For non-taxable products, set "Tax status" to "None".

---

Getting help

If none of the solutions in "Common issues" work for you, there are two ways to get help. To speed things up, attach the B2Brouter-related entries from debug.log and include your plugin, WordPress and WooCommerce versions.

1. B2Brouter support: open a support ticket from your account. eDocExchange customers have access to premium support, with priority ticket resolution and support seven days a week.
2. GitHub Issues: github.com/B2Brouter/b2brouter-woocommerce/issues