← Back to Blog

Booking Reference Numbers — Easier to Reference Than UUID

Every booking on ChargePeer has had a UUID — a unique identifier that looks like "a1b2c3d4-e5f6-7890-abcd-ef1234567890". It is great for databases and APIs, but terrible for human communication. When you contact support, you have to copy-paste a UUID fragment, or worse, read out 36 characters over the phone.

That workflow is gone. Every booking now gets a short, human-readable reference number — something you can read, say, and type without friction. The format is simple: "CHG-001", "CHG-002", "CHG-127" — a three-letter prefix followed by a zero-padded sequential number.

The reference number appears as a subtle gray pill badge on each booking card at /bookings, sitting next to the date in the card header. It replaces the old "Access: CP-XXXXXXXX" snippet that showed a truncated UUID — which was never meant to be a reference identifier.

Under the hood, the reference number is generated by a PostgreSQL sequence — `bookings_ref_seq` — which auto-increments with every new booking. The sequence is queried at insert time via `nextval()`, and the number is formatted as `CHG-NNN` before being stored in the new `reference_number` column on the `bookings` table.

The backend returns `reference_number` in both the create response (`POST /api/bookings/create`) and the list response (`GET /api/bookings/mine`). The frontend renders it as a pill badge with the same shape as the status badges but in a secondary text color — scannable without competing for attention.

This is a small UX improvement with outsized support impact. When a customer says "My booking CHG-042 was cancelled" instead of "My booking a1b2... something... was cancelled," every minute of the support conversation is productive. No more copy-paste, no more reading UUIDs aloud, no more typos in support tickets.

The sequence is initialized at 1 and increments monotonically. Existing bookings created before this feature was deployed will not have a reference number (the column defaults to NULL), and the frontend simply skips the badge when none is present. New bookings will automatically receive numbers starting from the current sequence value.

This is foundational for future features: we plan to add reference numbers to email notifications, push notifications, receipt PDFs, and the billing portal. The "CHG-" prefix identifies the resource type in any cross-referencing context — easily recognizable across the entire platform.