external_reference on invoices
Invoices accept an external_reference — your own order id — that you can filter by and that is enforced as unique.
ChangelogNew
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
The `status` filter on `GET /v1/invoices` accepts a comma-separated list, so one request covers several statuses.
Disbursements (suplidos): pass-through payments
Invoice lines carry a `line_type`. Set `SUPLIDO` to pass through amounts paid in your client’s name, outside the taxable base.