> ## 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.
# Customers
> The buyer record in Yuno. What the customer object is, when you need one, and how it ties to vaulting, checkout, subscriptions, and every payment.
A customer is Yuno's permanent record of one of your buyers. It holds their identity, documents, addresses, and metadata, and every vaulted payment method, subscription, and enrollment session attaches to it. Create one when you have the buyer's profile, keep the `customer_id` Yuno returns, and reuse it across [checkout sessions](/core-concepts/checkout-sessions), [payments](/core-concepts/payments), [tokens](/core-concepts/tokens), and [subscriptions](/api-reference/subscriptions/create).
## When you need a customer
| Flow | Customer required? |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `POST /v1/checkout/sessions` | **Yes.** A session cannot open without a `customer_id`. |
| `POST /v1/subscriptions` | **Yes.** A subscription is permanently tied to one customer. |
| Vaulting a payment method (one-click, recurring) | **Yes.** Every vaulted token is owned by exactly one customer. |
| `POST /v1/payments` with inline `customer` fields only | **No.** Guest payments work without a Yuno customer record, but you lose vaulting and reuse. |
## Create a customer
Replace the header values and body fields with your own test data.
```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -sS -X POST "https://api-sandbox.y.uno/v1/customers" \
-H "public-api-key: YOUR_PUBLIC_API_KEY" \
-H "private-secret-key: YOUR_PRIVATE_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"merchant_customer_id": "your-internal-user-123",
"first_name": "Dee",
"last_name": "Hock",
"email": "dee@hock.example",
"country": "US"
}'
```
```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark"}}
const res = await fetch('https://api-sandbox.y.uno/v1/customers', {
method: 'POST',
headers: {
'public-api-key': process.env.YUNO_PUBLIC_API_KEY,
'private-secret-key': process.env.YUNO_PRIVATE_SECRET_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
merchant_customer_id: 'your-internal-user-123',
first_name: 'Dee',
last_name: 'Hock',
email: 'dee@hock.example',
country: 'US',
}),
});
const data = await res.json();
console.log(res.status, data);
```
```python Python theme={"theme":{"light":"github-dark","dark":"github-dark"}}
import os
import requests
r = requests.post(
"https://api-sandbox.y.uno/v1/customers",
headers={
"public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
"private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
"Content-Type": "application/json",
},
json={
"merchant_customer_id": "your-internal-user-123",
"first_name": "Dee",
"last_name": "Hock",
"email": "dee@hock.example",
"country": "US",
},
timeout=30,
)
print(r.status_code, r.json())
```
On success you receive **HTTP 200** with a Yuno-generated `customer_id`. Store it next to your own user key.
```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"merchant_customer_id": "your-internal-user-123",
"first_name": "Dee",
"last_name": "Hock",
"email": "dee@hock.example",
"country": "US",
"created_at": "2026-04-14T12:00:00.000Z"
}
```
Field names in live responses follow the **[Customer object](/api-reference/customers/object)** reference (this sample is illustrative).
## Customer identifiers
| Identifier | Source | What you use it for |
| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `customer_id` | Returned by Yuno | Primary key in **[Customers API](/api-reference/customers/create)** paths and in payment payloads |
| `merchant_customer_id` | You set it on create | Stable link to your internal user; you can **[look up by external id](/api-reference/customers/get-by-external-id)** |
Persist `customer_id` in your datastore. You need it for enrolled payment methods, one-click flows, and profile updates.
## Document types
Most Latin American payment methods require identification on the customer (CPF and CNPJ in Brazil, CC / CE / NIT in Colombia, CURP and RFC in Mexico, and so on). Send document numbers **digits only**. No dots, dashes, or spaces. Example: CPF `123.456.789-01` → `12345678901`.
For the full per-country table of supported document types and formats, see [payment methods](/core-concepts/payment-methods#method-specific-requirements) and the [country reference](/reference/country-reference).
## Vaulted payment methods
Every vaulted token belongs to exactly one customer. A single customer can hold many methods of different types: cards, digital wallets (Apple Pay, Google Pay, Click to Pay), bank transfer enrollments, BNPL accounts, and payment links. All of them are retrieved from the same endpoint:
```http theme={"theme":{"light":"github-dark","dark":"github-dark"}}
GET /v1/customers/{customer_id}/payment-methods
```
Each entry in the response includes a `vaultedToken` you can pass as `payment_method.token` on a future payment, plus masked details safe to render to the buyer (last 4 digits for cards, masked keys for PIX, and so on). Unenrolled methods are excluded.
Typical uses:
* **One-click checkout.** Surface saved methods at the top of your checkout UI so repeat buyers skip re-entering data.
* **Subscriptions and recurring charges.** Reference a vaulted token when creating a subscription or a merchant-initiated transaction (MIT).
* **Method management.** Let customers review and remove their stored methods from an account page.
See [tokens](/core-concepts/tokens#list-vaulted-methods) for the request example and [List payment methods](/api-reference/payment-methods/list) for the full response schema.
## Customer in payment requests
When you call [Create payment](/api-reference/payments/create), attach a customer either by reference (`customer_id` pointing to an existing record), by sending the fields inline, or both. Many methods need specific fields. PIX and Boleto in Brazil need `customer.document` with a valid CPF or CNPJ; UPI in India needs a VPA; SEPA needs an IBAN. See [payment methods](/core-concepts/payment-methods#method-specific-requirements) for the per-method contract.
```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
"customer": {
"customer_id": "yuno-customer-id",
"email": "dee@hock.example",
"document": { "document_type": "CPF", "document_number": "12345678901" }
}
}
```
### Precedence when both are sent
If you pass `customer_id` **and** inline fields, the **inline values win for that payment**. The provider sees exactly what you sent on the request, not what's stored on the customer record. This lets you correct or enrich profile data per transaction without touching the stored customer.
After the payment is processed, Yuno **backfills empty fields** on the stored customer from your inline values. Populated fields are never overwritten by a payment.
| Field | Provider sees | Backfilled to the stored customer |
| ------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------- |
| `email`, `first_name`, `last_name`, `gender`, `date_of_birth`, `nationality`, `document`, `phone` | Inline if present, otherwise the stored value. | Only if the stored field is empty. |
| `billing_address`, `shipping_address` | Inline if present, otherwise the stored value. | Never. Addresses are request-scoped only. |
| `merchant_customer_id`, `country` | The stored customer's value. Not overridable per payment. | Never. |
A payment with `customer_id` plus inline values may silently update the stored customer the first time a field is filled in. If you need to keep the stored record frozen, use [Update customer](/api-reference/customers/update) explicitly rather than passing the fields on a payment. To intentionally edit the stored record, always prefer the Update endpoint. It's request-scoped vs. backfill-scoped and the intent is explicit.
## What next
Every field the Customer object supports.
Create a session and attach the customer to it.
Country and method requirements per region.
How vaulted methods attach to this customer.