Stable Reference ID
Stable Reference ID support
Merchants identify users with stableReferenceId, a permanent merchant-scoped identifier that is immutable once set. All new integrations must provide stableReferenceId. The API still accepts requests without it only so existing merchants can migrate off deprecated referenceId.
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) | Required for new integrations. Omitted in the API only during legacy transition from referenceId |
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 for existing merchants: integrations that only use referenceId keep working while they migrate. New merchants should always send stableReferenceId and should not rely on referenceId.