external_reference — tie an invoice to your order and dedupe by it
Invoices now accept an optional external_reference — your own order / cart / contract id — that BeeL. stores, returns, lets you filter by, and enforces as a business-uniqueness key. It's the right tool for "one invoice per order", separate from the Idempotency-Key (which guards request retries).
Invoices now accept an optional external_reference — your own order / cart / contract id — that BeeL. stores, returns, lets you filter by, and enforces as a business-uniqueness key. It's the right tool for "one invoice per order", separate from the Idempotency-Key (which guards request retries).
What else changed
external_referenceonPOST /v1/invoices— send your order id (e.g.ORD-2025-0042). It's stored, echoed back on reads, and filterable viaGET /v1/invoices?external_reference=ORD-2025-0042.- At most one live invoice per reference — creating a second standard/simplified invoice with the same
external_referencereturns409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE. Delete the existing one and you can recreate it. - It is NOT the
Idempotency-Key— the idempotency key protects request retries (use a fresh UUID per attempt) and survives deletion by design;external_referenceis a durable business key that reflects the current state. Use both, for different jobs. - Isolated per environment — the same reference can exist once in sandbox and once in live.
Endpoints
- POST/v1/invoicesAccepts optional external_reference; returns 409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE on a live duplicate
- GET/v1/invoicesNew external_reference query filter
Where to go next
Filter invoices by several statuses at once
The `status` filter on `GET /v1/invoices` now accepts a comma-separated list, so a single paginated request can return invoices in any of several statuses.
Suplidos: bill back payments made on behalf of your client
Invoice lines now carry a `line_type`. Set it to `SUPLIDO` to pass through amounts you paid in your client's name (art. 78.Tres.3 LIVA). Suplidos stay out of the taxable base, VAT and VeriFactu, and add to a new `total_to_pay` alongside the fiscal `invoice_total`.