> ## Documentation Index
> Fetch the complete documentation index at: https://yn-c9bb3266.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Customer
> Create a customer record. Returns a Yuno generated customer `id` you can reference in checkout sessions, payments, enrollments, and subscriptions.
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](/api-reference/checkout-sessions/create) via `customer_id`.
* Vault payment methods against the customer with [Create Customer Session](/api-reference/customer-sessions/create) and our SDKs.
* Charge a vaulted token by passing the customer to [Create Payment](/api-reference/payments/create).
* Drive recurring billing by attaching the customer to a [Subscription](/api-reference/subscriptions/create).
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](/api-reference/customers/get-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.
```bash Look up before create theme={"theme":{"light":"github-dark","dark":"github-dark"}}
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.
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.
```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
"phone": { "country_code": "55", "number": "11999990000" }
```
Yuno stores metadata as an ordered list of entries, not as a JSON object.
```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
"metadata": [
{ "key": "loyalty_tier", "value": "gold" },
{ "key": "signup_source", "value": "web" }
]
```
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).
`M` (male), `F` (female), or `NB` (non binary). Anything else returns HTTP 400.
Calendar date only. `1990-02-28` is valid. `1990-02-28T00:00:00Z` is not.
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](/api-reference/customers/get-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](/core-concepts/error-handling) for the full envelope shape and retry guidance.
## Related endpoints
* [Get Customer](/api-reference/customers/get) for `GET /v1/customers/{customer_id}`
* [Retrieve Customer by External ID](/api-reference/customers/get-by-external-id) for `GET /v1/customers/merchant-customer-id/{merchant_customer_id}`
* [List Customers](/api-reference/customers/list) for `GET /v1/customers`
* [Update Customer](/api-reference/customers/update) for `PATCH /v1/customers/{customer_id}`
* [Delete Customer](/api-reference/customers/delete) for `DELETE /v1/customers/{customer_id}`
## Related concepts
* [Customers](/core-concepts/customers) explains how customers work in Yuno.
* [Tokens](/core-concepts/tokens) explains how customer tokens and vaulting work.
* [Country reference](/reference/country-reference) lists document types and address requirements per country.
## OpenAPI
````yaml POST /v1/customers
openapi: 3.1.0
info:
title: Yuno Payments API
description: >-
Yuno payment orchestration platform — unified REST API for payments,
checkout sessions, customers, payment methods, subscriptions, payouts,
marketplace transfers, and banking connectivity across Latin America.
version: 1.0.0
contact:
name: Yuno Support
email: support@y.uno
url: https://docs.y.uno
license:
name: Proprietary
url: https://y.uno
servers:
- url: https://api-sandbox.y.uno
description: Sandbox
- url: https://api.y.uno
description: Production
security:
- publicApiKey: []
privateSecretKey: []
paths:
/v1/customers:
post:
tags:
- Customers
summary: Create customer
description: >-
Creates a new customer record. Returns the created `Customer` object
including a Yuno-generated `id` (UUID) you can use to reference the
customer in checkout sessions, payments, enrollments, and subscriptions.
**Required field:** only `merchant_customer_id`. Every other field is
optional, but providing as much data as possible (document, phone,
billing address) improves authorization, conversion, and
fraud-prevention rates with downstream payment providers.
**Uniqueness and safe retries:** `merchant_customer_id` must be unique
within your Yuno account. Sending the same value twice returns HTTP 400
with code `CUSTOMER_ID_DUPLICATED`. This is the dedupe mechanism for
this endpoint — set a stable `merchant_customer_id` and a retry will be
rejected rather than create a duplicate. To look up an existing customer
by your internal ID, use [Retrieve Customer by External
ID](/api-reference/customers/get-by-external-id).
operationId: createCustomer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
examples:
minimal:
summary: Minimal — only the required field
value:
merchant_customer_id: cust-internal-001
brazil_pix:
summary: Brazil — full payload for PIX/Boleto eligibility
value:
merchant_customer_id: cust-internal-001
first_name: Maria
last_name: Silva
email: maria.silva@example.com
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
colombia_pse:
summary: Colombia — full payload for PSE/Nequi eligibility
value:
merchant_customer_id: cust-internal-002
first_name: Carlos
last_name: Ramírez
email: carlos.ramirez@example.com
country: CO
nationality: CO
document:
document_type: CC
document_number: '1093333333'
phone:
country_code: '57'
number: '3132450765'
billing_address:
address_line_1: 'Calle 34 # 56 - 78'
city: Bogotá
state: Cundinamarca
country: CO
zip_code: '111111'
neighborhood: Chapinero
responses:
'201':
description: Customer created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'400':
description: >-
Invalid request — for example, a missing `merchant_customer_id`, a
`gender` outside the allowed enum, a partial `phone` object, or a
duplicate `merchant_customer_id` (`CUSTOMER_ID_DUPLICATED`).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
duplicate:
summary: Duplicate merchant_customer_id
value:
code: CUSTOMER_ID_DUPLICATED
messages:
- >-
A customer with this merchant_customer_id already exists
for this account.
invalid:
summary: Invalid request payload
value:
code: INVALID_REQUEST
messages:
- merchant_customer_id is required
'401':
description: '`public-api-key` or `private-secret-key` is missing or invalid.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: UNAUTHORIZED
messages:
- Unauthorized
'403':
description: The merchant account is not authorized to use the Customers API.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: FORBIDDEN
messages:
- Forbidden
x-codeSamples:
- lang: bash
label: cURL
source: |-
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": "maria.silva@example.com",
"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" }
]
}'
components:
schemas:
CustomerRequest:
type: object
description: >-
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.
required:
- merchant_customer_id
properties:
merchant_customer_id:
type: string
minLength: 3
maxLength: 255
description: >-
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](/api-reference/customers/get-by-external-id).
example: cust-internal-001
merchant_customer_created_at:
type: string
format: date-time
minLength: 27
maxLength: 27
description: >-
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.
example: '2024-01-15T12:34:56.123456Z'
first_name:
type: string
minLength: 3
maxLength: 255
description: >-
Customer's first name (legal first name as it appears on the
identification document).
example: Maria
last_name:
type: string
minLength: 3
maxLength: 255
description: >-
Customer's last name (legal surname as it appears on the
identification document).
example: Silva
email:
type: string
format: email
minLength: 3
maxLength: 255
description: >-
Customer's email address. Strongly recommended — required by most
APMs (PIX, Boleto, OXXO, PSE) and by 3DS challenge flows.
example: maria.silva@example.com
gender:
type: string
enum:
- M
- F
- NB
description: >-
Customer's gender. `M` (male), `F` (female), or `NB` (non-binary).
Any other value is rejected with HTTP 400.
example: F
date_of_birth:
type: string
format: date
minLength: 10
maxLength: 10
pattern: ^\d{4}-\d{2}-\d{2}$
description: Customer's date of birth in `YYYY-MM-DD` format.
example: '1990-02-28'
country:
type: string
pattern: ^[A-Z]{2}$
minLength: 2
maxLength: 2
description: Customer's country of residence. ISO 3166-1 alpha-2 code.
example: BR
nationality:
type: string
pattern: ^[A-Z]{2}$
minLength: 2
maxLength: 2
description: Customer's nationality. ISO 3166-1 alpha-2 code.
example: BR
document:
$ref: '#/components/schemas/CustomerDocument'
phone:
$ref: '#/components/schemas/CustomerPhone'
billing_address:
$ref: '#/components/schemas/CustomerAddress'
shipping_address:
$ref: '#/components/schemas/CustomerAddress'
metadata:
type: array
maxItems: 50
description: >-
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.
items:
$ref: '#/components/schemas/CustomerMetadataItem'
example:
merchant_customer_id: cust-internal-001
merchant_customer_created_at: '2024-01-15T12:34:56.123456Z'
first_name: Maria
last_name: Silva
email: maria.silva@example.com
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
Customer:
type: object
description: Customer object returned by Create, Get, List, and Update endpoints.
properties:
id:
type: string
format: uuid
description: >-
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:
type: string
description: Echoed from the request — your unique identifier for this customer.
example: cust-internal-001
merchant_customer_created_at:
type: string
nullable: true
format: date-time
description: Echoed from the request, or `null` if not supplied.
example: '2024-01-15T12:34:56.123456Z'
first_name:
type: string
nullable: true
example: Maria
last_name:
type: string
nullable: true
example: Silva
email:
type: string
nullable: true
format: email
example: maria.silva@example.com
gender:
type: string
nullable: true
enum:
- M
- F
- NB
- null
example: F
date_of_birth:
type: string
nullable: true
example: '1990-02-28'
country:
type: string
nullable: true
example: BR
nationality:
type: string
nullable: true
example: BR
document:
allOf:
- $ref: '#/components/schemas/CustomerDocument'
nullable: true
phone:
allOf:
- $ref: '#/components/schemas/CustomerPhone'
nullable: true
billing_address:
allOf:
- $ref: '#/components/schemas/CustomerAddress'
nullable: true
shipping_address:
allOf:
- $ref: '#/components/schemas/CustomerAddress'
nullable: true
metadata:
type: array
nullable: true
description: >-
Echoed from the request. Returns an empty array (or omitted) when no
metadata was provided.
items:
$ref: '#/components/schemas/CustomerMetadataItem'
created_at:
type: string
format: date-time
description: >-
Server-generated ISO 8601 timestamp of when the customer record was
created.
example: '2026-03-01T10:00:00.000000Z'
updated_at:
type: string
format: date-time
description: >-
Server-generated ISO 8601 timestamp of the last update to the
customer record.
example: '2026-03-01T10:00:00.000000Z'
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: maria.silva@example.com
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'
Error:
type: object
description: >-
Standard error envelope returned by every Yuno service for any 4xx or
5xx response. Top level. `code` is a stable SCREAMING_SNAKE_CASE
identifier. `messages` is always an array of strings, even when there is
only one entry. There is no `error` wrapper, no singular `message`, no
`type`, no `details`. See the Error handling guide for the full code
catalog.
required:
- code
- messages
properties:
code:
type: string
description: >-
Stable, machine readable identifier. Branch on this in your client.
Common values include `BAD_REQUEST`, `VALIDATION_ERROR`,
`INVALID_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`,
`TOO_MANY_REQUESTS`, `INTERNAL_ERROR`, `BAD_GATEWAY`,
`SERVICE_UNAVAILABLE`, plus business codes like
`CUSTOMER_ID_DUPLICATED`, `RECIPIENT_NOT_FOUND`, `INVALID_STATE`,
and the `PROVIDER_*` family for downstream provider errors.
example: VALIDATION_ERROR
messages:
type: array
description: >-
Human readable details. Validation errors put one entry per failed
field, formatted `"fieldName message"`.
items:
type: string
example:
- merchant_customer_id must not be blank
example:
code: VALIDATION_ERROR
messages:
- amount must be greater than 0
- country must not be blank
CustomerDocument:
type: object
description: >-
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.
required:
- document_type
- document_number
properties:
document_type:
type: string
minLength: 3
maxLength: 6
description: >-
Type of identification document. Common values per country: Brazil —
`CPF` (individuals), `CNPJ` (businesses); Colombia — `CC`, `CE`,
`NIT`, `PP`, `TI`; Mexico — `CURP`, `RFC`; Argentina — `DNI`,
`CUIT`, `CUIL`; Chile — `RUT`, `RUN`; Peru — `DNI`, `RUC`; Uruguay —
`CI`, `RUT`; United States — `SSN`; international — `PASSPORT`. See
the [Country Reference](/reference/country-reference) for the
document required by each payment method.
example: CPF
document_number:
type: string
minLength: 3
maxLength: 40
description: >-
Document number, digits only, no separators or formatting. Length
depends on the document type (CPF: 11 digits, CNPJ: 14 digits, CURP:
18 chars, RFC: 12-13 chars, DNI-AR: 7-8 digits).
example: '12345678901'
example:
document_type: CPF
document_number: '12345678901'
CustomerPhone:
type: object
description: >-
Customer's phone number, split into country calling code and the local
number. Both fields are required when the `phone` object is sent.
required:
- country_code
- number
properties:
country_code:
type: string
minLength: 1
maxLength: 3
description: Country calling code (E.164 country code) without the leading `+`.
example: '57'
number:
type: string
minLength: 1
maxLength: 32
description: >-
Subscriber number without the country code. Digits only — do not
include spaces, dashes, or parentheses.
example: '3132450765'
example:
country_code: '57'
number: '3132450765'
CustomerAddress:
type: object
description: >-
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.
properties:
address_line_1:
type: string
minLength: 3
maxLength: 255
description: Primary street address (street name and number).
example: 'Calle 34 # 56 - 78'
address_line_2:
type: string
minLength: 3
maxLength: 255
description: Additional address detail (apartment, suite, floor, unit).
example: Apartamento 502, Torre I
building_number_1:
type: string
minLength: 3
maxLength: 255
description: >-
Primary building number (used in markets where the street name and
the building number are stored separately, e.g., Brazil).
example: '12'
building_number_2:
type: string
minLength: 3
maxLength: 255
description: >-
Secondary building number (e.g., complement, block, or tower
reference).
example: '14'
city:
type: string
minLength: 3
maxLength: 255
description: City name.
example: Bogotá
state:
type: string
minLength: 3
maxLength: 255
description: >-
State, province, or department. Use the full name or the local
administrative code as appropriate for the country.
example: Cundinamarca
zip_code:
type: string
minLength: 5
maxLength: 10
description: Postal / ZIP code.
example: '111111'
neighborhood:
type: string
minLength: 1
maxLength: 255
description: >-
Neighborhood, district, or borough. Required by some Brazilian
acquirers when processing Boleto and PIX.
example: Chapinero
country:
type: string
pattern: ^[A-Z]{2}$
minLength: 2
maxLength: 2
description: ISO 3166-1 alpha-2 country code.
example: CO
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
CustomerMetadataItem:
type: object
description: Single key/value entry inside the `metadata` array.
required:
- key
- value
properties:
key:
type: string
maxLength: 48
description: Metadata entry key. Maximum 48 characters.
example: loyalty_tier
value:
type: string
maxLength: 512
description: Metadata entry value. Maximum 512 characters.
example: gold
example:
key: loyalty_tier
value: gold
securitySchemes:
publicApiKey:
type: apiKey
in: header
name: public-api-key
description: Your public API key from the Yuno Dashboard
privateSecretKey:
type: apiKey
in: header
name: private-secret-key
description: Your private secret key (server-side only)
````