# external_reference is now external_ref

The invoice field first announced as external_reference is now called external_ref — the old name still works when you write, but responses no longer return it.

Aug 13, 2026 · Breaking

The invoice field first announced as `external_reference` is now called `external_ref`. Responses already emit the new name; the old one is still accepted when you write, as a deprecated alias.

## What breaks

- **Reads are the urgent half.** The response field is `external_ref`. Code reading `invoice.external_reference` off a response gets `undefined` — silently, with no error. This is the trap: writes keep working through the alias, so an integration can look healthy while the value it reads back is empty.
- **Writes still work.** Sending `external_reference` in the body of a create-invoice call is still honoured, including the `409 INVOICE_DUPLICATE_EXTERNAL_REFERENCE` uniqueness check. It is a deprecated alias, not the field name.
- **The query filter is deprecated, not removed.** `GET /v1/invoices?external_reference=…` still filters. On the company-scoped route (`GET /v1/companies/{company_id}/invoices`), `external_ref` is the only name accepted.

## Does this affect you?

- Grep your integration for `external_reference`. Any hit is either a deprecated alias to rename, or — if it reads from a response — a bug already returning `undefined`.
- Replay one recent create-invoice call and read `external_ref` back off the response. If it carries your order id, your writes are fine and only the reads need renaming.
- If you filter invoices by your order id, check which route you call. The company-scoped route never accepted the old name.

## The retirement calendar

No removal date is announced. The alias stays until one is, and it will appear here — with a `Sunset` header on the affected calls — before anything stops working.

- **Today** — Both names accepted on writes; responses emit `external_ref` only. Migrate at your own pace — nothing is scheduled to break.
- **When a date is set** — It is announced here first, and the affected calls start carrying a `Sunset` header you can read from your own traffic.
- **After that date** — The `external_reference` alias is withdrawn and the field is ignored on writes.

Your writes keep working until the alias is withdrawn. Your reads are already returning nothing if they look for `external_reference` on a response.

## Where to go next

- [Idempotency guide](/guides/idempotency)
- [Create an invoice](/invoices/createInvoice)

## Why you may have missed this

The field was first announced as
[`external_reference`](/changelog/invoice-external-reference), with that name in
every example, and renamed shortly after. That entry stays published as the
record of the original feature — so if you integrated from it, the name you
copied is the old one.

This note is the correction. The earlier entry is not being edited: what it said
was true when it shipped.

## What to change

```diff
  const invoice = await beel.invoices.create({
    // …
-   external_reference: order.id,
+   external_ref: order.id,
  });

- console.log(invoice.external_reference);  // undefined
+ console.log(invoice.external_ref);
```

The read is the urgent half. The write keeps working through the alias; the read
returns `undefined`, with no error to tell you.

## See also

- [Idempotency guide](/guides/idempotency) — how `external_ref` differs from the `Idempotency-Key`, and why you want both.
- [external_reference on invoices](/changelog/invoice-external-reference) — the original announcement, and the feature this renames.

---

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