A prefix ID is a composite string identifier designed to be self-describing: the prefix tells a developer (and a support engineer) what kind of object the ID refers to, while the suffix provides uniqueness. Stripe popularized this pattern with cus_, pi_, ch_, and sub_ prefixes. UUID v7 as the suffix adds time-ordered uniqueness to the self-describing prefix pattern.
Structure
cus_018fbe3a-4c5d-7b12-8f3e-1a2b3c4d5e6f
├──┘└──────────────────────────────────────┘
prefix UUID v7 suffix
| Component | Example | Purpose |
|---|---|---|
| Prefix | cus_ | Type identifier — human-readable |
| Separator | _ | Visual delimiter (optional) |
| Suffix | UUID v7 | Unique, time-ordered |
TypeScript implementation
import { v7 as uuidv7 } from 'uuid';
type Prefix = 'cus' | 'ord' | 'inv' | 'pmt' | 'ses';
function generatePrefixId(prefix: Prefix): string {
return `${prefix}_${uuidv7()}`;
}
function extractUuid(prefixId: string): string {
const idx = prefixId.indexOf('_');
return prefixId.slice(idx + 1); // UUID v7 portion
}
function extractPrefix(prefixId: string): string {
return prefixId.slice(0, prefixId.indexOf('_'));
}
function extractTimestamp(prefixId: string): Date {
const uuid = extractUuid(prefixId);
const hex = uuid.replace(/-/g, '').slice(0, 12);
return new Date(parseInt(hex, 16));
}
// Usage
const customerId = generatePrefixId('cus'); // "cus_018fbe3a-..."
const orderId = generatePrefixId('ord'); // "ord_018fbe3b-..."
// Prefix IDs from the same millisecond sort by random bits
console.log([orderId, customerId].sort()); // prefix sort — "cus_" < "ord_"
Database storage
-- TEXT column stores the full prefix ID
CREATE TABLE customers (
id TEXT NOT NULL PRIMARY KEY, -- e.g. 'cus_018fbe3a-...'
email TEXT NOT NULL UNIQUE,
name TEXT NOT NULL
);
-- Cursor pagination still works — same prefix means same sort key length
SELECT * FROM customers
WHERE id > 'cus_018fbe3a-4c5d-7b12-8000-000000000000'
ORDER BY id
LIMIT 20;
Validation
const PREFIX_ID_REGEX = /^[a-z]{2,8}_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
function isValidPrefixId(id: string): boolean {
return PREFIX_ID_REGEX.test(id);
}
function assertPrefix(id: string, expected: Prefix): void {
if (!id.startsWith(`${expected}_`)) {
throw new Error(`Expected ${expected} prefix, got: ${id}`);
}
}
Prefix ID vs plain UUID v7
| Property | Plain UUID v7 | Prefix ID + UUID v7 |
|---|---|---|
| Human-readable type | No | Yes (cus_, ord_) |
| Lexicographic sort | Yes | Yes (same prefix = same length) |
| Misuse prevention | No | Yes (assertPrefix()) |
| Storage size | 36 chars | 40+ chars |
| Standard format | RFC 9562 | Custom |
Further reading
- Opaque Identifier — UUID Design Principle
- Sortable ID — Time-Ordered Identifiers
- Base62 Encoding — Compact UUID Representation
- UUID v4 vs UUID v7
- What is a UUID
Frequently asked questions
What is a prefix ID?
A prefix ID is a string identifier with a human-readable type prefix followed by a separator and a unique suffix. Stripe uses this pattern extensively: cus_ for customers, pi_ for payment intents, ch_ for charges. The prefix tells developers what type of entity the ID refers to without querying the database. Stripe uses Base58-encoded random suffixes; UUID v7 is an RFC-standard alternative. See Opaque Identifier.
How do I build a prefix ID with UUID v7?
Concatenate the prefix with a UUID v7 string: `cus_${uuidv7()}` produces cus_018fbe3a-4c5d-7b12-8f3e-1a2b3c4d5e6f. Store the full prefix ID in a TEXT column. The UUID v7 suffix preserves lexicographic sort order (chronological) even with the prefix — since all IDs of the same type have the same prefix length. See Sortable ID.
Should I strip hyphens from UUID v7 when building prefix IDs?
Many systems strip hyphens for compactness: cus_018fbe3a4c5d7b128f3e1a2b3c4d5e6f. Stripping hyphens preserves lexicographic sort order because the UUID v7 timestamp prefix is still in the leading characters. If you want a shorter representation, use Base32 or Base58 encoding — but note this loses the standard UUID format. See Base62 Encoding for compact UUID alternatives.