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
ComponentExamplePurpose
Prefixcus_Type identifier — human-readable
Separator_Visual delimiter (optional)
SuffixUUID v7Unique, 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

PropertyPlain UUID v7Prefix ID + UUID v7
Human-readable typeNoYes (cus_, ord_)
Lexicographic sortYesYes (same prefix = same length)
Misuse preventionNoYes (assertPrefix())
Storage size36 chars40+ chars
Standard formatRFC 9562Custom

Further reading

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.