`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.
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 readinginvoice.external_referenceoff a response getsundefined— 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_referencein the body of a create-invoice call is still honoured, including the409 INVOICE_DUPLICATE_EXTERNAL_REFERENCEuniqueness 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_refis 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 returningundefined. - Replay one recent create-invoice call and read
external_refback 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.
- TodayBoth names accepted on writes; responses emit
external_refonly. Migrate at your own pace — nothing is scheduled to break. - When a date is setIt is announced here first, and the affected calls start carrying a
Sunsetheader you can read from your own traffic. - After that dateThe
external_referencealias 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
Why you may have missed this
The field was first announced as
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
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 — how
external_refdiffers from theIdempotency-Key, and why you want both. external_reference— the original announcement — the feature this renames.
Changelog
Every change to the BeeL. API, newest first — what moved, when the old way stops working, and how to tell whether it affects you.
Resources under the NIF
An account can now hold several NIFs, each named in the path. The old flat routes are deprecated with a Sunset date and a successor — here's what moved where, when the old routes retire, and how to tell whether it affects you.