---
title: "2026-04-14 · External customer IDs, plus early API fixes"
description: "external_customer_id becomes a first-class identifier across usage, reservations, topups, subscriptions, and webhooks. Plus a display_name field and reservation status lookups."
order: 11
date: "2026-04-14"
---

# External customer IDs, plus early API fixes

Two batches shipped the same day. The first gave your own customer IDs equal standing with QuotaStack's. The second closed four small gaps found in review.

## Added — `external_customer_id` as a first-class identifier

Four endpoints now take `external_customer_id` in the body, next to the existing `customer_id`: `POST /v1/usage`, `/v1/usage/batch`, `/v1/reservations`, and `/v1/topups/grant`. Exactly one of the two is required.

A new URL family mirrors this: `/v1/customer-by-external-id/{external_id}/...`. It sits beside `/v1/customers/{id}/...` and supports the same calls.

`POST /v1/subscriptions` now also takes `external_customer_id`. The old `customer_id` form still works.

Every customer-scoped [webhook](/docs/concepts/webhooks) envelope now carries both `customer_id` and `external_customer_id`, when the customer record still exists at delivery time.

See [Customer Identification](/docs/concepts/customer-identification) for when to use which form.

## Added — `display_name` on customers

An optional label, up to 200 characters, for your own dashboards and search. QuotaStack does not use it for anything else.

```json
{ "external_id": "user_alice", "display_name": "Alice" }
```

## Added — reservation status and listing

`GET /v1/reservations/{id}` returns one [reservation](/docs/concepts/reservations)'s current status. Use it to check whether a reservation is still open before you commit or release it.

Two list endpoints cover a customer's reservations: `GET /v1/customers/{id}/reservations` and its external-id twin. Both take `status`, `cursor`, and `limit`.

See [Reservations](/docs/concepts/reservations#checking-reservation-status).