# external_reference on invoices

Invoices accept an `external_reference` — your own order id — that you can filter by and that is enforced as unique.

Jul 18, 2026 · New

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_reference` on `POST /v1/invoices`** — send your order id (e.g. `ORD-2025-0042`). It's stored, echoed back on reads, and filterable via `GET /v1/invoices?external_reference=ORD-2025-0042`.
- **At most one live invoice per reference** — creating a second standard/simplified invoice with the same `external_reference` returns `409 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_reference` is 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/invoices` — Accepts optional external_reference; returns 409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE on a live duplicate
- `GET /v1/invoices` — New external_reference query filter

## Where to go next

- [Idempotency guide](/guides/idempotency)
- [Error reference](/errors/INVOICE_DUPLICATE_EXTERNAL_REFERENCE)

---

Full OpenAPI spec: https://docs.beel.es/api/openapi