Customers

Customers belong to one merchant and one mode. A live key never reads or changes test customers, and a test key never reads or changes live customers.

Created during payment

When a payment succeeds, Utopia matches the customer by lower-cased email in the current merchant and mode. If no match exists, it creates a customer. If a match already exists, the payment uses that customer and fills an empty phone number without overwriting an existing one.

This means you can create a checkout with only customer.email and let the successful payment create the customer record.

Create one first

Create a customer when you want to attach your own metadata before payment:

curl https://utopia-payments.com/api/v1/customers \
  -X POST \
  -H "Authorization: Bearer $UTOPIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: customer-1001" \
  -d '{
    "name": "Layla Hassan",
    "email": "layla@example.com",
    "phone_number": "+971501234567",
    "metadata": { "crm_id": "1001" }
  }'

Email is unique within a merchant and mode. Creating or updating a customer to an email already in use returns CUSTOMER_EXISTS. Phone numbers use E.164 format. Use GET /customers?email=layla@example.com to find a customer by email, or filter payments and subscriptions with customer_id.