Every entity in Paddle has a unique identifier called a Paddle ID. Paddle IDs are made up of a prefix for the kind of entity, followed by a unique string of 26 alphanumeric characters.
Prefixes are typically three characters, but can be longer. They're distinctive, so it's easy to tell what kind of entity you're working with from a Paddle ID alone.
ID prefixes
| Entity | Prefix | Regex |
|---|---|---|
| Address | add_ | ^add_[a-z\d]{26}$ |
| Adjustment | adj_ | ^adj_[a-z\d]{26}$ |
| API key | apikey_ | ^apikey_[a-z\d]{26}$ |
| API key exposure | apkexp_ | ^apkexp_[a-z\d]{26}$ |
| Business | biz_ | ^biz_[a-z\d]{26}$ |
| Client-side token | ctkn_ | ^ctkn_[a-z\d]{26}$ |
| Customer | ctm_ | ^ctm_[a-z\d]{26}$ |
| Customer portal session | cpls_ | ^cpls_[a-z\d]{26}$ |
| Discount | dsc_ | ^dsc_[a-z\d]{26}$ |
| Discount group | dsg_ | ^dsg_[a-z\d]{26}$ |
| Event | evt_ | ^evt_[a-z\d]{26}$ |
| Notification | ntf_ | ^ntf_[a-z\d]{26}$ |
| Notification log | ntflog_ | ^ntflog_[a-z\d]{26}$ |
| Notification setting | ntfset_ | ^ntfset_[a-z\d]{26}$ |
| Notification simulation | ntfsim_ | ^ntfsim_[a-z\d]{26}$ |
| Simulation run | ntfsimrun_ | ^ntfsimrun_[a-z\d]{26}$ |
| Simulation run event | ntfsimevt_ | ^ntfsimevt_[a-z\d]{26}$ |
| Payment method | paymtd_ | ^paymtd_[a-z\d]{26}$ |
| Price | pri_ | ^pri_[a-z\d]{26}$ |
| Product | pro_ | ^pro_[a-z\d]{26}$ |
| Report | rep_ | ^rep_[a-z\d]{26}$ |
| Subscription | sub_ | ^sub_[a-z\d]{26}$ |
| Transaction | txn_ | ^txn_[a-z\d]{26}$ |
Some entities don't have Paddle IDs. Event types, simulation types, metrics, and pricing previews are reference data or calculated responses, so they don't have a persistent ID.
Work with IDs
Paddle automatically generates IDs for you when you create entities using the API or dashboard. Use Paddle IDs to refer to entities throughout the Paddle platform.
Create entities
When creating entities using the API, Paddle returns the new Paddle ID for the entity in the response.
Get entities
When reading, updating, or deleting entities, use the ID to refer to the correct entity. For example:
/products/{product_id} Paddle ID of the product to get.
List entities
When working with list endpoints, Paddle uses the Paddle ID of the entity you're working with as the cursor for pagination.
/products?after={product_id} Return entities after the specified cursor.
Paddle ID of the product to use as the cursor.
Relate entities
Where entities are related, use Paddle IDs to link them. For example:
- When creating a price, pass a
product_idto set the product that a price relates to. - When creating a transaction, pass a
customer_idandaddress_idto set who to bill. - When the
subscription.createdevent occurs, it includes thetransaction_idof the transaction that resulted in this subscription being created.
Sort by ID
Paddle IDs are lexicographically sortable. Sorting by Paddle ID results in the same order as sorting by the creation date of an entity.