Stripe keys and IDs

stripe-keys-and-ids.tsv

@davidfilkins Are all Stripe IDs in the format {prefix}_{24 alphanumeric characters}?

No:

Very old Stripe objects (prior to 2012) had "traditional UUIDs" as object-identifiers (according to this article by a Stripe employee) - so any active Stripe account today made prior to 2012 will have at least some prefix-less object-identifiers in it (as Stripe's object-identifiers are ostensibly immutable, so any object created before prefixes were added will retain its prefix-less object-id):

https://dev.to/stripe/designing-apis-for-humans-object-ids-3o5a

Stripe has been using this prefixing technique since 2012, and as far as I know, we’re the first ones to implement it at scale. [...] Before 2012, all Object IDs at Stripe looked more like traditional UUIDs. If you were an early Stripe adopter you might notice that your account ID still looks like this, without the prefix.

However, for all new Stripe objects since then they'll have the prefix. I didn't start using Stripe until around 2014 so I've never encountered a prefix-less object-id in my life - so given the benefits of performing method precondition assertions (i.e. parameter validation) I use this regex and it's never failed on valid input in the ~8 years I've been using it:^[a-z]{2,5}_[0-9A-Za-z]{8,58}$ (use with case-sensitive mode).

The {8,58} quantifier in my regex is nothing more than an educated hope that Stripe would never do something as silly as have an actual 256-char-long object-id value (despite their threats to do so...]) - as I've almost always defaulted to using varchar(64) for RDBMS columns for storing Stripe object-ids (using a low varchar max-length n value is important to constrain maximum row-size to avoid off-table string storage which really harms DB performance).

That said, in the past 8 years I've been using Stripe I've never encountered a Stripe object-id longer than 34 characters, including the type-prefix (excepting things like Hosted Invoice PDF URIs of the form live_[0-9A-Za-z]{100+} which tend to be around 100-102 chars long.... but also consider that in those 8 years I've never ventured beyond Stripe's Checkout/Customers/Products/Subscriptions/Payments/Invoices functionality; as I haven't touched the rest of Stripe's offerings and it's entirely possible that much longer object-ids exist there. YMMV etc.

https://stripe.com/docs/upgrades#what-changes-does-stripe-consider-to-be-backwards-compatible

Stripe considers the following changes to be backwards-compatible:
[...]
Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
[...]
You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length.

...but given Stripe's consistent and clear-messaging to expect 255-char-long object-ids I think unless you have an overriding and compelling technical reason to restrict string-length to something shorter then you should stick with treating object-ids as purely opaque case-sensitive strings up-to-255 chars, and don't even attempt to regex-them or inspect their contents. I know I do in my own code, but it's me who will be suffering the consequences of my decision-making, not you.

There was actually a breaking-change in Stripe's API's December 2019 and May 20198 updates that wouldn't have affected people treating ids as opaque strings, but likely would have failed in my own code:

https://stripe.com/docs/upgrades#2019-12-03

• The id field of all invoice line items have changed and are now prefixed with il_. The new id has consistent prefixes across all line items, is globally unique, and can be used for pagination.
• You can no longer use the prefix of the id to determine the source of the line item. Instead use the type field for this purpose.

https://stripe.com/docs/upgrades#2018-05-21

• The id field of invoice line items of type=subscription no longer can be interpreted as a subscription ID, but instead is a unique invoice line item ID.

...though curiously the same update does describe a constraint on the characters inside Coupon, SKU, Customer, Product, and Plan ids:

Coupon, SKU, customer, product and plan ids may only contain alphanumeric and _- characters on creation.

...curious. And no Stripe API updates since then have abrogated that point either.

---

@faridanthony They use {prefix}_{ulid}. Read more here: https://blog.daveallie.com/ulid-primary-keys?utm_source=pocket_mylist

That article summarizes ulid, but it doesn't claim that Stripe is using ulid. Indeed, @turakvlad is correct in that Stripe object-ids aren't ulids, simply because ulids are case-insensitive but Stripe object-ids are case-sensitive (so anyone who forgot to specify COLLATE <some-case-sensitive-collation>) in their CREATE TABLE statement is going to have problems...).

---

Another curious thing, is that Stripe's object-ids are also clearly not entirely random: there's definitely a time-component of some significance (or some other monotonic change) that I've observed in some ids, like evt_ ids for Stripe Event objects. Here's a screenshot of some logged Stripe events from one of my databases, showing how Events all have similar leading characters that seem to correspond to the date+time:

...so I assume that dev.to article's claims of being "random" represents a drastic over-simplification of whatever their real scheme is ...which could still be based on incrementing integer values in their underlying database (and consider that truly random primary-key values are a good way to wreck your INSERT performance and is why SQL Server prefers NEWSEQUENTIALID() instead of NEWID() if you're using a GUID/UUID as a PK).

There are a couple more which are not listed:

tcc_
This is referenced as a "connection_context_id" in the Terminal API

tmars_
This is referenced as a "reader_rpc_session_token" and a "sdk_rpc_session_token" in the Terminal API

pss_live_
This is referenced as a "stripe_session_token" in the Terminal API

finvp_ and binvp_
These are both used as fee IDs in a Payout Transaction breakdown. Can be found in the Dashboard API at dashboard.stripe.com/v1/transfers/po_XXXXXXX/transactions

One more for the list sub_sched_ for subscription schedules

One more: ca_<foo> for stripe connect client_ids (for building the oauth redirect uri, amongst other things)

Adding some associated dashboard URLs (the ID itself would be appended to the URL).

Prefix	Description	Notes	URL
ch_	Charge ID	Identifier for a Charge object.	https://dashboard.stripe.com/payments/
cus_	Customer ID	Identifier for a Customer object.	https://dashboard.stripe.com/customers/
il_	Invoice Line Item ID	Identifier for a Invoice Line Item object.	https://dashboard.stripe.com/subscriptions/
in_	Invoice ID	Identifier for an Invoice object.	https://dashboard.stripe.com/invoices/
pi_	Payment Intent ID	Identifier for a Payment Intent object.	https://dashboard.stripe.com/payments/
po_	Payout ID	Identifier for a Payout object.	https://dashboard.stripe.com/payouts/
price_	Price ID	Identifier for a Price object.	https://dashboard.stripe.com/prices/
prod_	Product ID	Identifier for a Product object.	https://dashboard.stripe.com/products/
promo_	Promo Code ID	Identifier for a promo/coupon code.	https://dashboard.stripe.com/promotion_codes/
seti_	Setup Intent ID	Identifier for a Setup Intent object.	https://dashboard.stripe.com/setup_intents/
sub_	Subscription ID	Identifier for a Subscription object.	https://dashboard.stripe.com/subscriptions/

Prefix	Description
ri_	return_intent
rist_	return_intent_secret_token
retatt_	return_attempt
retmst_	return_method_secret_token
retm_	return_method

You might find it helpful to know that em_ is used for emails sent out by Stripe.

If you're interested in IDs with similar properties, there is a plethora.

There's also UUIDv7 now!

• RFC 9562
• uuid7.com
• A nice comparison with ULID

Shameless plug: I'm making a Python library to generate Stripe-like IDs, based on UUIDv7 and Crockford’s base32: https://pypi.org/project/prettyid/