prefixed-ids

name	prefixed-ids
description	This skill should be used when the user is designing ID formats for API resources, implementing type-safe identifiers, choosing between UUID and prefixed IDs, generating IDs with KSUID or ULID, creating ID validation, or following Stripe's prefixed ID pattern. Covers prefix conventions, ID generation, validation, and debugging benefits.
version	1.0.0

Every ID Should Declare Its Type

When a support engineer sees cus_NffrFeUfNV2Hib in a log line, they know it is a customer. When they see 550e8400-e29b-41d4-a716-446655440000, they know nothing. Stripe prefixes every ID with a short type indicator, and that seemingly small decision compounds across debugging, routing, type safety, log analysis, and cross-service communication. Adopt this pattern for every resource in your API.

The Prefix Pattern

Every ID follows the format {type}_{random}:

cus_NffrFeUfNV2Hib          -- customer
ord_01HXK3GJ5V8WJKPT2MNR   -- order
pi_3MtwBwLkdIwHu7ix28a3     -- payment intent

The prefix is a short, lowercase abbreviation of the resource type. The underscore is a fixed separator. The random part is a collision-resistant, alphanumeric string.

Format Rules

Follow these constraints for every prefixed ID:

• Prefix length: 2-5 lowercase characters. Short enough to read at a glance, long enough to be unambiguous.
• Separator: Always a single underscore. Never a hyphen, colon, or dot.
• Random part: Base62 characters (a-zA-Z0-9). URL-safe, no special characters. 14-27 characters depending on the generation strategy.
• Total length: 18-30 characters. Short enough to paste in Slack, long enough to be collision-free.

Prefix Catalog

Define a canonical prefix for every resource type in your API. Maintain this as a living registry -- never reuse a prefix for a different resource.

Prefix	Resource	Example
usr_	User	usr_01HXK3GJ5V8WJKP
org_	Organization	org_2ZutauDiLLuKvLgb
ord_	Order	ord_01ARZ3NDEKTSV4RR
prod_	Product	prod_NWjs8kKbJWmuuc
inv_	Invoice	inv_1MtHbELkdIwHu7ix
pay_	Payment	pay_3MtwBwLkdIwHu7ix
sub_	Subscription	sub_1MowQVLkdIwHu7ix
wh_	Webhook Endpoint	wh_1MqVTHLkdIwHu7ix
evt_	Event	evt_9Kx2mPbQ7rTvYw4j
sess_	Session	sess_2dH3VUuCJRx7wnlv
tok_	Token	tok_1MioVOLkdIwHu7ix
key_	API Key	key_4eC39HqLyjWDarjt
cus_	Customer	cus_NffrFeUfNV2Hib
price_	Price	price_1MoBy5LkdIwHu7ix
txn_	Transaction	txn_3MmlLrLkdIwHu7ix

ID Generation: Choosing the Random Part

The prefix gives you type safety. The random part must give you uniqueness, collision resistance, and ideally time-sortability. Pick one strategy and use it everywhere.

Strategy	Sortable	Length (with prefix)	URL-Safe	Best For
ULID	Yes (ms)	~30 chars	Yes (Crockford Base32)	General-purpose API IDs. B-tree friendly, chronological ORDER BY id.
KSUID	Yes (sec)	~31 chars	Yes (Base62)	High-entropy IDs with time sorting. 128 bits of randomness per second.
nanoid	No	~28 chars	Yes	Short IDs where time ordering is irrelevant. Smallest library.
UUID v7	Yes (ms)	~36 chars	No (hex)	Standards compliance. Broad ecosystem support. Longer than alternatives.

Recommendation: Use ULID or KSUID. Time-sortability means created_at is embedded in the ID itself, which enables cursor-based pagination without a separate timestamp column. Both produce sequential values that avoid random B-tree page splits, giving you better database write performance than UUID v4 or nanoid.

Do not use UUID v4. It is universally supported but completely opaque, not sortable, and unnecessarily long.

Implementation pattern:

import { ulid } from "ulid";

function generateId(prefix: string): string {
  return `${prefix}_${ulid()}`;
}

generateId("cus");  // "cus_01HXK3GJ5V8WJKPT2MNR9QZK1"
generateId("ord");  // "ord_01HXK3GK7RABCDE8FGHJ3KLMN"

The ULID portion encodes a millisecond timestamp in the first 10 characters (Crockford Base32), followed by 16 characters of cryptographic randomness. IDs generated within the same millisecond are lexicographically ordered by their random component, which means ORDER BY id gives you chronological order without a separate created_at index.

Database Considerations

Store prefixed IDs as TEXT or VARCHAR columns, not as binary. The human-readability of prefixed IDs is their primary advantage -- converting them to binary for storage defeats the purpose and makes database debugging harder.

Primary key indexing. Time-sortable random parts (ULID, KSUID) produce monotonically increasing values within each prefix. This means inserts append to the end of the B-tree index rather than causing random page splits. The result is significantly better write throughput than UUID v4, which scatters inserts across the entire index.

Querying by type. Because all IDs for a given resource share the same prefix, you can filter by type with a prefix scan: WHERE id LIKE 'cus_%'. This is efficient on a B-tree index because the shared prefix means all matching rows are physically adjacent.

Foreign keys. Prefixed IDs work normally as foreign keys. The prefix adds a few bytes of overhead per row, but the debugging benefits far outweigh the marginal storage cost. A typical prefixed ID with ULID is 30 characters -- comparable to a UUID's 36 characters with hyphens.

Validation

Validate prefixed IDs at the API boundary before touching the database. A pi_ ID passed to a /customers endpoint should return a 400 immediately -- no query needed.

Regex pattern for validation:

^[a-z]{2,5}_[a-zA-Z0-9]{14,27}$

This catches the prefix (2-5 lowercase letters), the underscore separator, and the random part (14-27 alphanumeric characters). Adjust the random part length to match your generation strategy.

Type-specific validation: Check that the prefix matches the expected resource type for the endpoint. If the route is /v1/customers/:id, the ID must start with cus_. If it starts with ord_, reject it with a clear error message:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Expected customer ID (prefix 'cus_'), got 'ord_01HXK3GJ5V8WJKP'",
    "param": "id"
  }
}

This eliminates an entire class of bugs where IDs are passed to the wrong endpoint. Without prefixes, a bare UUID sent to the wrong endpoint produces a confusing "not found" error instead of a clear type mismatch.

Request body validation. Apply the same validation to IDs in request bodies, not just path parameters. When a client sends { "customer_id": "ord_abc123" } in a POST body, reject it immediately. The prefix makes the mismatch detectable without a database round-trip.

Polymorphic ID resolution. In webhook payloads, event logs, and audit trails, a single field may contain IDs of different types. Use the prefix to route to the correct handler:

function resolveResource(id: string) {
  const parsed = parseId(id);
  switch (parsed.prefix) {
    case "cus": return customerService.get(id);
    case "ord": return orderService.get(id);
    case "inv": return invoiceService.get(id);
    default:   throw new Error(`Unknown resource type: ${parsed.prefix}`);
  }
}

Why This Matters: The Debugging Multiplier

Prefixed IDs pay dividends across every layer of the stack:

Log analysis. Grep your application logs for pi_ to find all payment intent activity. Grep for cus_ to trace a customer's journey. With bare UUIDs, you need surrounding context to know what a log entry refers to.

# Find all payment-related activity
grep "pay_" /var/log/app.log

# Count orders vs. invoices in today's logs
grep -c "ord_" /var/log/app/2026-02-22.log
grep -c "inv_" /var/log/app/2026-02-22.log

Support tickets. When a user pastes ord_01ARZ3NDEKTSV4RR into a support ticket, the agent immediately knows this is an order and navigates to the orders dashboard. No database lookup to determine the resource type.

Cross-service communication. In a microservices architecture, IDs flow through queues, events, and caches. A prefixed ID is self-describing -- any service that encounters it knows what type of resource it references without parsing surrounding context.

Preventing cross-type confusion. Without prefixes, passing a user ID where an order ID is expected is a silent bug that produces a "not found" error. With prefixes, the mismatch is caught at the API boundary with a clear, actionable error.

Observability dashboards. Build Datadog, Splunk, or CloudWatch queries that filter by prefix. A query for pi_3MtwBw* immediately scopes to a single payment intent. A query for evt_ surfaces all events. This works because the prefix is embedded in the value itself, not in metadata that might be missing from some log entries.

Anti-Patterns

Auto-incrementing integers. They leak volume information (customer #50,000 tells competitors your scale), enable enumeration attacks (trivial to scrape /users/1 through /users/50000), and are not globally unique across services or tables. Never expose sequential integers in a public API.

Bare UUIDs. 550e8400-e29b-41d4-a716-446655440000 is globally unique but tells you nothing about what it represents. Every log line, support ticket, and queue message requires additional context to interpret. UUID v4 also produces random values that cause B-tree page splits in database indexes.

Inconsistent formats. Mixing prefixed IDs for some resources, UUIDs for others, and integers for the rest creates cognitive overhead for every developer who touches the API. Pick one format and enforce it everywhere.

Reusing prefixes. If usr_ once meant "user" and you repurpose it for "usage record," every existing log, support script, and integration breaks. Prefixes are permanent. Retire them; never reassign.

Underscores in prefixes. The prefix sub_sched_ is ambiguous -- is the prefix sub or sub_sched? Keep prefixes as single tokens without underscores. Use a distinct abbreviation instead (e.g., schd_ for subscription schedule).

Examples

Working implementations in examples/:

• examples/prefixed-id-generator.md -- Complete ID generation utility with prefix registry, generation, validation, and parsing in Node.js and Python
• examples/id-middleware-validation.md -- Express and FastAPI middleware that validates prefixed IDs in route params, returning 400 on invalid format

Review Checklist

When reviewing code that handles resource IDs:

• Every resource type has a registered prefix in the prefix catalog
• All IDs follow the {prefix}_{random} format with an underscore separator
• Prefixes are 2-5 lowercase characters with no underscores
• The random part uses a time-sortable strategy (ULID or KSUID preferred)
• ID validation happens at the API boundary, before any database query
• Type mismatches return a 400 error with a message naming the expected prefix
• No auto-incrementing integers are exposed in any public-facing endpoint
• No bare UUIDs are used as primary identifiers in API responses
• The prefix catalog is maintained as a single source of truth in code
• IDs are URL-safe (no special characters beyond the underscore separator)
• No prefix is reused or reassigned to a different resource type
• Cross-service messages include prefixed IDs that are self-describing