Stable Reference ID
Stable Reference ID support
Merchants can now pass a stableReferenceId alongside the existing referenceId when identifying users. This new field is immutable once set and is intended for merchants who need a permanent, unchanging identifier.
A new computed field effectiveReferenceId is returned in all user profile responses and SDK callbacks. It equals stableReferenceId when present, otherwise falls back to referenceId. This gives integrators a single canonical ID to use.
New fields
| Field | Description | Writable | Behavior |
|---|---|---|---|
stableReferenceId | Stable merchant-scoped user ID | Yes (immutable once set) | Optional, for merchants who need an ID that never changes |
effectiveReferenceId | Computed: stableReferenceId if set, otherwise referenceId | Read-only | Always present in responses and callbacks |
Deprecation of referenceId
referenceId is now deprecated and will be removed in a future release. We recommend migrating to stableReferenceId for all new integrations. Existing integrations that only use referenceId continue to work unchanged — there is no migration deadline at this time.
Backward compatibility
This change is fully backward compatible. Existing integrations that only use referenceId see no change in behavior. Adoption of stableReferenceId is incremental.