Typed IDs
Every Decal resource ID encodes the resource type and API mode in a structured string format.
Every Decal resource ID follows the pattern:
{prefix}_{mode}_{id}prefix— identifies the resource type (ordfor orders,csfor checkout sessions, etc.)mode— a PlatformMode value:livefor production,testfor sandboxid— a unique base-36 identifier
This means the ID itself tells you what the resource is and which environment it belongs to. An
ord_test_... ID can never be confused with a cs_live_... ID, and you can tell at a glance
whether a resource came from your live or test environment.
PlatformMode
Every ID and API key encodes the environment it belongs to. PlatformMode is a string union of the
two valid modes:
| Value | Description |
|---|---|
live | Production environment. Real transactions, real money. |
test | Sandbox environment. No real money moves. Use sk_test_... API keys to access. |
The mode embedded in a resource's ID always matches the API key used to create it —
- a
sk_test_...key can only create..._test_...resources - a
sk_live_...key can only create..._live_...resources
ID types
| Type | Format | Example |
|---|---|---|
OrderId | ord_{PlatformMode}_{id} | ord_live_clx8k2m9abc |
CheckoutSessionId | cs_{PlatformMode}_{id} | cs_live_clx8k2m9abc |
CheckoutLinkId | cl_{PlatformMode}_{id} | cl_live_clx8k2m9abc |
CustomerId | cust_{PlatformMode}_{id} | cust_live_clx8k2m9abc |
LocationId | loc_{PlatformMode}_{id} | loc_live_clx8k2m9abc |
PaymentId | pay_{PlatformMode}_{id} | pay_live_clx8k2m9abc |
TransactionId | tx_{PlatformMode}_{id} | tx_live_clx8k2m9abc |
IntegrationId | int_{PlatformMode}_{id} | int_live_clx8k2m9abc |
Where {PlatformMode} is the PlatformMode value for the resource's environment.
TypeScript types
If you're using TypeScript, these IDs are defined as template literal types:
type PlatformMode = "live" | "test";
type OrderId = `ord_${PlatformMode}_${string}`;
type CheckoutSessionId = `cs_${PlatformMode}_${string}`;
type CheckoutLinkId = `cl_${PlatformMode}_${string}`;
type CustomerId = `cust_${PlatformMode}_${string}`;
type LocationId = `loc_${PlatformMode}_${string}`;
type PaymentId = `pay_${PlatformMode}_${string}`;
type TransactionId = `tx_${PlatformMode}_${string}`;
type IntegrationId = `int_${PlatformMode}_${string}`;Template literal types make it impossible to accidentally pass an OrderId where a
CheckoutSessionId is expected, and the compiler surfaces the mistake immediately.