Many platforms use two kinds of identifiers on purpose. Public surfaces use UUIDs so resources are hard to guess. Inside the database, integer keys stay for fast joins and legacy compatibility.

This guide explains which one to use when you build dashboards, integrations, or admin workflows.

The rule of thumb

Use this	When
UUID (`merchant_uuid`, `customer_uuid`)	URLs, shareable links, public `GET`/`PATCH` paths, request bodies from browsers and partner apps
Integer (`id`, `userId`, `agent_id`, case id)	Staff accounts, agents, payment cases, audit rows, and anything already keyed by legacy numeric IDs

Think of the UUID as the address on the envelope. The integer is the row number in the filing cabinet.

Merchants

Every merchant (tenant on the platform) typically has:

merchant_uuid — exposed in API responses and used in routes
internal numeric id — used only inside the database (often omitted from public payloads)

Public merchant API

GET /api/merchants/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response includes merchant_uuid, not a numeric merchant id.

{
  "merchant_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Acme Payments Ltd",
  "city": "London",
  "country": "GB"
}

Do not call /api/merchants/1 — numeric paths should be rejected (400). Use the UUID from list, search, or onboarding responses.

Admin portal URLs

Admin routes use the same UUID in the browser:

https://admin.example.com/merchants/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Team management APIs follow the same pattern:

GET  /api/admin/merchants/{merchantUuid}/team
POST /api/admin/merchants/{merchantUuid}/team

Payment workflows

When creating or updating a case (e.g. onboarding, dispute, payout review), pass the merchant UUID in the body:

{
  "merchant_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Filter lists with the same field:

GET /api/cases?merchant_uuid=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Customers

End-customers often expose:

customer_uuid — preferred for customer portals and account APIs
customer_reference — human-readable support/search reference (e.g. CUS-10482)
internal numeric id — only for privileged ops or compliance roles

Customer-facing session responses may emphasize UUID + reference and hide the internal id where policy requires it.

GET /api/accounts/{customer_uuid}/activity

What stays numeric

These are commonly still integers by design:

Resource	Example field	Typical use
Portal user	`userId` / `id` in JWT	Login, team invites, impersonation
Agent	`agent_id`	Assignments, queues, performance views
Payment case	case `id`	Case detail, escrow, status transitions
Merchant team	`userId` on team rows	Resend invite, update team member

Merchant team endpoints often use UUID for the merchant and integer for the user:

POST /api/admin/merchants/{merchantUuid}/team/{userId}/resend-invite

Integration tips

List merchants and copy merchant_uuid from the JSON — do not assume sequential integers like 1, 2, 3.
Treat UUIDs as opaque strings; validate format (uuid) but do not parse meaning from them.
OpenAPI specs usually mark UUID path params with format: uuid.

Summary

UUID = safe, stable, public identifier for merchants and customers.
Integer = internal and legacy identifiers for users, agents, and cases.
Merchant routes and admin URLs should use UUID; numeric merchant paths are intentionally blocked.

When in doubt, use the UUID in anything a user could bookmark, share, or scrape from a URL bar.