README

Generate compliant e-invoices (PDF, XRechnung 3.0, ZUGFeRD 2.3/2.4) from Magento orders via the invoice-api.xhub.io service.

Live formats today: PDF, XRechnung 3.0 (DE B2G), ZUGFeRD 2.3/2.4 (DE/AT hybrid PDF+XML)
Coming Q3 2026: Factur-X, FatturaPA, Facturae, ebInterface, UBL, ISDOC, NAV
License: OSL-3.0 (Open Software License 3.0) — the Adobe Commerce Marketplace standard
Module ID: Xhubio_InvoiceApiXhub
Composer package: xhubio/magento2-invoice-api-xhub

Screenshots



Admin Dashboard after the plugin processed two test orders	Stores → Configuration → Sales → Invoice-api.xhub — all three sections expanded

General settings: API key, format, trigger, number format	Seller Details with IBAN/BIC fields (required for ZUGFeRD B2B)

Sales → Orders list	Order detail page with the Invoice-api.xhub metabox

A 16-page PDF User-Guide with all installation, configuration and troubleshooting steps lives at docs/Invoice-api-xhub-User-Guide-v1.0.0.pdf.

Requirements

Magento 2.4+ / Adobe Commerce 2.4+
PHP 7.4+
MySQL 8.0+ or MariaDB 10.4+
Elasticsearch 7.17+ (Magento 2.4.x default catalog search backend)
An invoice-api.xhub.io account — sign up at https://console.invoice-api.xhub.io

Install — Composer (recommended)

composer require xhubio/magento2-invoice-api-xhub
bin/magento module:enable Xhubio_InvoiceApiXhub
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

For developer-mode installs you can skip setup:di:compile; for production deploys it's required.

Install — manual (ZIP from GitHub)

Download the latest magento2-invoice-api-xhub.zip from https://github.com/xhubio/magento2-invoice-api-xhub/releases
Unzip into <magento-root>/app/code/Xhubio/InvoiceApiXhub/
Run the same bin/magento commands as in the Composer install above

Configure

Open the Admin panel -> Stores -> Configuration -> Sales -> Invoice-api.xhub
Set your API Key (get one at https://console.invoice-api.xhub.io/api-keys)
Set your Seller Details (name, VAT ID, address, email — these go on every invoice)
Pick a Format (PDF / XRechnung / ZUGFeRD) and Country (14 EU countries)
Choose the Auto-Generate Trigger — typically on_complete so an invoice is generated when an order reaches the "complete" state
Optional: set a PDF Template ID from https://console.invoice-api.xhub.io/pdf/templates for custom branding
Save Config and Flush Cache

Use

Automatic generation

When an order transitions to the configured trigger state (default: complete), the module:

Maps the order to the invoice-api.xhub.io schema
Calls the API to generate the file
Stores the file under pub/media/invoice-api-xhub/<order_id>/
Writes a row in xhubio_invoice_meta
Adds a status-history comment on the order

If Attach to Order Email is enabled, the file is attached to the customer order confirmation.

Manual generation

On the order view page in admin, scroll to the Invoice-api.xhub section to:

See the current invoice status (number, format, country, generated timestamp)
Click Generate invoice (or Re-generate) to trigger a run on demand
Click Download to fetch the file directly

Invoice number tokens

The Invoice Number Format setting accepts these tokens:

Token	Expands to
`{order_number}`	Magento order increment id (e.g. `000000123`)
`{order_id}`	Internal entity id
`{year}`	Year of order creation (e.g. `2026`)
`{month}`	2-digit month
`{day}`	2-digit day
`{seq}`	Next sequence value (atomic, yearly reset)
`{seq:0000}`	Same, zero-padded to 4 digits

Default: INV-{order_number}. A common production pattern: INV-{year}-{seq:0000}.

The sequence is atomic at the DB level via INSERT ... ON DUPLICATE KEY UPDATE current = LAST_INSERT_ID(current+1) — two simultaneous generates can never share a number even under load.

Schema

Two tables are created on setup:upgrade:

xhubio_invoice_seq
  period       varchar(32)  PRIMARY KEY    -- "all" | "YYYY" | "YYYY-MM"
  current      bigint unsigned             -- last allocated number
  updated_at   timestamp                   -- last increment

xhubio_invoice_meta
  id              int unsigned    PRIMARY KEY AUTO_INCREMENT
  order_id        int unsigned    UNIQUE  FK -> sales_order.entity_id ON DELETE CASCADE
  invoice_number  varchar(64)
  format          varchar(32)            -- pdf | xrechnung | zugferd
  country         varchar(2)             -- ISO 3166-1 alpha-2
  template_id     varchar(36) NULL       -- UUID of custom PDF template, or NULL for default
  api_hash        char(64)               -- sha256 of API response (idempotency)
  filename        varchar(255)           -- as returned by API
  file_path       varchar(512)           -- relative to pub/media/invoice-api-xhub/
  generated_at    timestamp

GDPR

The module subscribes to:

customer_delete_after — purges all invoice meta + files for that customer's orders
sales_order_delete_after — purges meta + file for that one order

Hard-delete of orders is uncommon (tax retention rules — UStG: 10 years), but the hooks are there for the rare case.

Business model

Free open-source connector (OSL-3.0). The paid product is the invoice-api.xhub.io service — your API key represents your service subscription. See docs/BUSINESS-MODEL.md for details.

License

OSL-3.0 (Open Software License 3.0) — the Adobe Commerce Marketplace standard license. See LICENSE.md for the full text.

Support

GitHub Issues: https://github.com/xhubio/magento2-invoice-api-xhub/issues
Service support: https://invoice-api.xhub.io/support

xhubio / magento2-invoice-api-xhub

Maintainers

Package info

Statistics

Security