SDK Reference
Sync User Profile
Track and catalog your app's users inside SettleSettle's directory. Call this when an end-user signs in, registers, or updates their details in your app.
This action is 100% idempotent — safe to trigger repeatedly. If the user doesn't exist, they're instantly registered; if they do, their metadata updates.
typescript
const user = await settle.users.sync({
externalUserId: 'user_998877', // Required — your unique ID for them
email: 'lexi@example.com', // Optional — user email
name: 'Lexi Thompson', // Optional — full name
metadata: { // Optional — any custom context
plan: 'premium',
cohort: 'may_2026',
},
})
console.log(user.id) // internal SettleSettle user IDUsage Strategies — The Vibe Coder's Playbook#
Just sprinkle this in your server-side auth handler. Right after your db records the user's session, fire this off to keep SettleSettle in perfect lock-step alignment.
| Parameter | Type | Required | Description |
|---|---|---|---|
externalUserId | string | Yes | The user ID string from your primary database. |
email | string | No | Used to link automatic financial records. |
name | string | No | Standard visual identifier for Dashboard lookups. |
metadata | object | No | Extra telemetry keys you want visible in User Profiler. |