Create Customer

Create a customer record. Returns a Yuno generated customer id you can reference in checkout sessions, payments, enrollments, and subscriptions.

POST /v1/customers

cURL

cURL

curl --request POST \
  --url https://api-sandbox.y.uno/v1/customers \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'public-api-key: YOUR_PUBLIC_API_KEY' \
  --header 'private-secret-key: YOUR_PRIVATE_SECRET_KEY' \
  --data '{
    "merchant_customer_id": "cust-internal-001",
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "[e-mail]",
    "gender": "F",
    "date_of_birth": "1990-02-28",
    "country": "BR",
    "nationality": "BR",
    "document": {
      "document_type": "CPF",
      "document_number": "12345678901"
    },
    "phone": {
      "country_code": "55",
      "number": "11999990000"
    },
    "billing_address": {
      "address_line_1": "Av. Paulista, 1000",
      "address_line_2": "Apto 502",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "zip_code": "01310100",
      "neighborhood": "Bela Vista"
    },
    "metadata": [
      { "key": "loyalty_tier", "value": "gold" }
    ]
  }'

201

Example

{ "id": "c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f", "merchant_customer_id": "cust-internal-001", "merchant_customer_created_at": "2024-01-15T12:34:56.123456Z", "first_name": "Maria", "last_name": "Silva", "email": "[e-mail]", "gender": "F", "date_of_birth": "1990-02-28", "country": "BR", "nationality": "BR", "document": { "document_type": "CPF", "document_number": "12345678901" }, "phone": { "country_code": "55", "number": "11999990000" }, "billing_address": { "address_line_1": "Av. Paulista, 1000", "address_line_2": "Apto 502", "city": "São Paulo", "state": "SP", "country": "BR", "zip_code": "01310100", "neighborhood": "Bela Vista" }, "shipping_address": { "address_line_1": "Av. Paulista, 1000", "address_line_2": "Apto 502", "city": "São Paulo", "state": "SP", "country": "BR", "zip_code": "01310100", "neighborhood": "Bela Vista" }, "metadata": [ { "key": "loyalty_tier", "value": "gold" }, { "key": "signup_source", "value": "web" } ], "created_at": "2026-03-01T10:00:00.000000Z", "updated_at": "2026-03-01T10:00:00.000000Z" }

Only merchant_customer_id is required. Every other field is optional, but the more information you supply (document, phone, billing address) the better the authorization, conversion, and fraud prevention rates with downstream payment providers. This is especially true for APMs such as PIX, Boleto, OXXO, PSE, and SPEI.

When to use this endpoint

Create a customer once, then reuse the returned id (or your own merchant_customer_id) in every subsequent operation:

• Reference the customer in Create Checkout Session via customer_id.
• Vault payment methods against the customer with Create Customer Session and our SDKs.
• Charge a vaulted token by passing the customer to Create Payment.
• Drive recurring billing by attaching the customer to a Subscription.

You can also create customers implicitly during a payment by sending the customer block on a payment request. Creating them explicitly first is recommended whenever you have the buyer’s profile available before checkout, since it lets you enrich the record over time.

Uniqueness and safe retries

merchant_customer_id is unique per Yuno account. POSTing twice with the same value returns HTTP 400 with code CUSTOMER_ID_DUPLICATED. Use Retrieve Customer by External ID to look up an existing record before creating a new one.

This endpoint does not accept an X-Idempotency-Key header. The dedupe mechanism is the unique business key. Pick a stable merchant_customer_id for each customer in your system, and a retry will be rejected by the database constraint instead of creating a duplicate.

Look up before create

curl --request GET \
  --url 'https://api-sandbox.y.uno/v1/customers/merchant-customer-id/cust-internal-001' \
  --header 'public-api-key: YOUR_PUBLIC_API_KEY' \
  --header 'private-secret-key: YOUR_PRIVATE_SECRET_KEY'

Field shape gotchas

A few fields commonly trip up integrators. Get these right and the rest of the contract is straightforward.

phone is an OBJECT, not a string

Send phone as an object with country_code and number (digits only, no +, no spaces, no dashes). If you send the phone object, both nested fields are required.

"phone": { "country_code": "55", "number": "11999990000" }

metadata is an ARRAY of {key, value}, not a map

Yuno stores metadata as an ordered list of entries, not as a JSON object.

"metadata": [
  { "key": "loyalty_tier", "value": "gold" },
  { "key": "signup_source", "value": "web" }
]

document is required by most LATAM APMs

Although document is optional at the schema level, PIX, Boleto, OXXO, PSE, SPEI, Nequi, and most other Latin American APMs will reject the eventual payment if the customer has no document. Pass document_type and document_number (digits only). Common types per country: CPF/CNPJ (BR), CC/CE/NIT (CO), CURP/RFC (MX), RUT/RUN (CL), DNI/RUC (PE), CI/RUT (UY).

gender enum is exactly M | F | NB

M (male), F (female), or NB (non binary). Anything else returns HTTP 400.

date_of_birth uses YYYY-MM-DD, not ISO 8601 with time

Calendar date only. 1990-02-28 is valid. 1990-02-28T00:00:00Z is not.

merchant_customer_created_at is ISO 8601 with microseconds

The customer’s registration date in your platform, not when you call this endpoint. Format: YYYY-MM-DDTHH:MM:SS.ffffffZ (for example, 2024-01-15T12:34:56.123456Z).

Errors

HTTP	Code	When
400	VALIDATION_ERROR	Body fails schema validation (missing merchant_customer_id, gender outside enum, malformed JSON). The messages array names every failed field.
400	CUSTOMER_ID_DUPLICATED	A customer with this merchant_customer_id already exists for your account. Look up the existing record with Retrieve Customer by External ID.
401	UNAUTHORIZED	public-api-key or private-secret-key is missing or invalid.
403	FORBIDDEN	The merchant account is not authorized to use the Customers API.

See Error handling for the full envelope shape and retry guidance.

Related endpoints

• Get Customer for GET /v1/customers/{customer_id}
• Retrieve Customer by External ID for GET /v1/customers/merchant-customer-id/{merchant_customer_id}
• List Customers for GET /v1/customers
• Update Customer for PATCH /v1/customers/{customer_id}
• Delete Customer for DELETE /v1/customers/{customer_id}

Related concepts

• Customers explains how customers work in Yuno.
• Tokens explains how customer tokens and vaulting work.
• Country reference lists document types and address requirements per country.

Authorizations

public-api-key · string · header · required

Your public API key from the Yuno Dashboard

private-secret-key · string · header · required

Your private secret key (server-side only)

Body

application/json

Request body for creating or updating a customer. Only merchant_customer_id is required; every other field is optional, but the more information you supply, the better the downstream authorization, conversion, and fraud-prevention rates.

merchant_customer_id · string · required

Your unique identifier for this customer in your own platform. Must be unique within your Yuno account — POSTing twice with the same value returns a CUSTOMER_ID_DUPLICATED 400 error. Use this ID to retrieve the customer later via Retrieve Customer by External ID.

Required string length: 3 - 255

Example:

"cust-internal-001"

merchant_customer_created_at · string<date-time>

Date the customer was originally registered on your platform. ISO 8601 format with microseconds and Z suffix (e.g., 2024-01-15T12:34:56.123456Z). Used by some risk providers as a tenure signal.

Required string length: 27

Example:

"2024-01-15T12:34:56.123456Z"

first_name · string

Customer's first name (legal first name as it appears on the identification document).

Required string length: 3 - 255

Example:

"Maria"

last_name · string

Customer's last name (legal surname as it appears on the identification document).

Required string length: 3 - 255

Example:

"Silva"

email · string<email>

Customer's email address. Strongly recommended — required by most APMs (PIX, Boleto, OXXO, PSE) and by 3DS challenge flows.

Required string length: 3 - 255

Example:

"[e-mail]"

gender · enum<string>

Customer's gender. M (male), F (female), or NB (non-binary). Any other value is rejected with HTTP 400.

Available options: M, F, NB

Example:

"F"

date_of_birth · string<date>

Customer's date of birth in YYYY-MM-DD format.

Required string length: 10

Pattern: ^\d{4}-\d{2}-\d{2}$

Example:

"1990-02-28"

country · string

Customer's country of residence. ISO 3166-1 alpha-2 code.

Required string length: 2

Pattern: ^[A-Z]{2}$

Example:

"BR"

nationality · string

Customer's nationality. ISO 3166-1 alpha-2 code.

Required string length: 2

Pattern: ^[A-Z]{2}$

Example:

"BR"

document · object

Customer's identification document. Both fields are required when the document object is sent. Yuno does not enforce a fixed enum on document_type; pass the local code expected by the destination payment method.

Show child attributes

Example:

{
  "document_type": "CPF",
  "document_number": "12345678901"
}

phone · object

Customer's phone number, split into country calling code and the local number. Both fields are required when the phone object is sent.

Show child attributes

Example:

{
  "country_code": "57",
  "number": "3132450765"
}

billing_address · object

Postal address. Used for both billing_address and shipping_address. All fields are optional, but providing as much detail as possible improves authorization rates and downstream fraud-prevention scoring.

Show child attributes

Example:

{
  "address_line_1": "Calle 34 # 56 - 78",
  "address_line_2": "Apartamento 502, Torre I",
  "city": "Bogotá",
  "state": "Cundinamarca",
  "country": "CO",
  "zip_code": "111111",
  "neighborhood": "Chapinero"
}

shipping_address · object

Postal address. Used for both billing_address and shipping_address. All fields are optional, but providing as much detail as possible improves authorization rates and downstream fraud-prevention scoring.

Show child attributes

Example:

{
  "address_line_1": "Calle 34 # 56 - 78",
  "address_line_2": "Apartamento 502, Torre I",
  "city": "Bogotá",
  "state": "Cundinamarca",
  "country": "CO",
  "zip_code": "111111",
  "neighborhood": "Chapinero"
}

metadata · object[]

Custom key/value pairs you want to attach to the customer. Maximum 50 entries; each key ≤ 48 characters and each value ≤ 512 characters. Returned verbatim on retrieval.

Maximum array length: 50

Show child attributes

Response

201

application/json

Customer created successfully

Customer object returned by Create, Get, List, and Update endpoints.

id · string<uuid>

Yuno's unique customer identifier (UUID v4). Use this value when referencing the customer in checkout sessions, payments, enrollments, and subscriptions.

Example:

"c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f"

merchant_customer_id · string

Echoed from the request — your unique identifier for this customer.

Example:

"cust-internal-001"

merchant_customer_created_at · string<date-time> | null

Echoed from the request, or null if not supplied.

Example:

"2024-01-15T12:34:56.123456Z"

first_name · string | null

Example:

"Maria"

last_name · string | null

Example:

"Silva"

email · string<email> | null

Example:

"[e-mail]"

gender · enum<string> | null

Available options: M, F, NB, null

Example:

"F"

date_of_birth · string | null

Example:

"1990-02-28"

country · string | null

Example:

"BR"

nationality · string | null

Example:

"BR"

document · object

Customer's identification document. Both fields are required when the document object is sent. Yuno does not enforce a fixed enum on document_type; pass the local code expected by the destination payment method.

Show child attributes

Example:

{
  "document_type": "CPF",
  "document_number": "12345678901"
}

phone · object

Customer's phone number, split into country calling code and the local number. Both fields are required when the phone object is sent.

Show child attributes

Example:

{
  "country_code": "57",
  "number": "3132450765"
}

billing_address · object

Postal address. Used for both billing_address and shipping_address. All fields are optional, but providing as much detail as possible improves authorization rates and downstream fraud-prevention scoring.

Show child attributes

Example:

{
  "address_line_1": "Calle 34 # 56 - 78",
  "address_line_2": "Apartamento 502, Torre I",
  "city": "Bogotá",
  "state": "Cundinamarca",
  "country": "CO",
  "zip_code": "111111",
  "neighborhood": "Chapinero"
}

shipping_address · object

Postal address. Used for both billing_address and shipping_address. All fields are optional, but providing as much detail as possible improves authorization rates and downstream fraud-prevention scoring.

Show child attributes

Example:

{
  "address_line_1": "Calle 34 # 56 - 78",
  "address_line_2": "Apartamento 502, Torre I",
  "city": "Bogotá",
  "state": "Cundinamarca",
  "country": "CO",
  "zip_code": "111111",
  "neighborhood": "Chapinero"
}

metadata · object[] | null

Echoed from the request. Returns an empty array (or omitted) when no metadata was provided.

Show child attributes

created_at · string<date-time>

Server-generated ISO 8601 timestamp of when the customer record was created.

Example:

"2026-03-01T10:00:00.000000Z"

updated_at · string<date-time>

Server-generated ISO 8601 timestamp of the last update to the customer record.

Example:

"2026-03-01T10:00:00.000000Z"