> ## 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.

# The Customer Object

> Represents a customer in Yuno's system, used across checkout sessions, payments, enrollments, and subscriptions.

The Customer object stores buyer information used across checkout sessions, payments, enrollments, and subscriptions. Customers can be created explicitly via the [Create Customer](/api-reference/customers/create) endpoint or implicitly during payment creation.

<Info>
  Customer records are shared across all payment methods and providers. Creating a customer once allows you to reference them in every subsequent transaction using their `id` or `merchant_customer_id`.
</Info>

## Object fields

<ResponseField name="id" type="string">
  Yuno's unique customer identifier (UUID v4). Server-generated.

  Example: `c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f`
</ResponseField>

<ResponseField name="merchant_customer_id" type="string" required>
  Your own internal customer identifier. Non-blank string, unique per Yuno account. Used for reconciliation and to retrieve a customer with [Retrieve Customer by External ID](/api-reference/customers/get-by-external-id).

  Example: `cust-internal-001`
</ResponseField>

<ResponseField name="merchant_customer_created_at" type="string | null">
  The customer's original registration date on **your** platform. Use ISO 8601 with microseconds and `Z` suffix. For example, `2024-01-15T12:34:56.123456Z`.
</ResponseField>

<ResponseField name="first_name" type="string | null">
  Customer's first name (legal first name as shown on the identification document).

  Example: `Maria`
</ResponseField>

<ResponseField name="last_name" type="string | null">
  Customer's last name (legal surname as shown on the identification document).

  Example: `Silva`
</ResponseField>

<ResponseField name="email" type="string | null">
  Customer's email address. Strongly recommended. Required by most APMs (PIX, Boleto, OXXO, PSE) and by 3DS challenge flows.

  Example: `maria.silva@example.com`
</ResponseField>

<ResponseField name="gender" type="string | null">
  Customer's gender.

  Values: `M` (male), `F` (female), `NB` (non-binary).
</ResponseField>

<ResponseField name="date_of_birth" type="string | null">
  Date of birth in `YYYY-MM-DD` format (calendar date only. No time component).

  Example: `1990-02-28`
</ResponseField>

<ResponseField name="country" type="string | null">
  Customer's country of residence. ISO 3166-1 alpha-2 code.

  Example: `BR`
</ResponseField>

<ResponseField name="nationality" type="string | null">
  Customer's nationality. ISO 3166-1 alpha-2 code.

  Example: `BR`
</ResponseField>

<ResponseField name="document" type="object | null">
  Customer's identification document. Required by most Latin American APMs at payment time.

  <Expandable title="document">
    <ResponseField name="document_type" type="string" required>
      Type of identification document. Common values per country: Brazil. `CPF`, `CNPJ`; 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`.
    </ResponseField>

    <ResponseField name="document_number" type="string" required>
      Document number, digits only (no separators or formatting). Examples: `12345678901` (CPF. 11 digits), `12345678000190` (CNPJ. 14 digits).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="phone" type="object | null">
  Customer's phone number. **Both nested fields are required when `phone` is present.**

  <Expandable title="phone">
    <ResponseField name="country_code" type="string" required>
      Country calling code (E.164 country code) without the leading `+`. Up to 3 characters.

      Example: `55`
    </ResponseField>

    <ResponseField name="number" type="string" required>
      Subscriber number without the country code. Digits only. No spaces, dashes, or parentheses.

      Example: `11999990000`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="billing_address" type="object | null">
  Customer's billing address. All nested fields are optional, but completeness improves authorization rates and 3DS frictionless eligibility.

  <Expandable title="billing_address">
    <ResponseField name="address_line_1" type="string">
      Primary street address.

      Example: `Av. Paulista, 1000`
    </ResponseField>

    <ResponseField name="address_line_2" type="string">
      Additional address detail (apartment, suite, floor, unit).
    </ResponseField>

    <ResponseField name="building_number_1" type="string">
      Primary building number (used in markets where street name and building number are stored separately, e.g., Brazil).
    </ResponseField>

    <ResponseField name="building_number_2" type="string">
      Secondary building number (complement, block, or tower reference).
    </ResponseField>

    <ResponseField name="city" type="string">
      City name.
    </ResponseField>

    <ResponseField name="state" type="string">
      State, province, or department.
    </ResponseField>

    <ResponseField name="zip_code" type="string">
      Postal / ZIP code.
    </ResponseField>

    <ResponseField name="neighborhood" type="string">
      Neighborhood, district, or borough.
    </ResponseField>

    <ResponseField name="country" type="string">
      ISO 3166-1 alpha-2 country code.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipping_address" type="object | null">
  Customer's shipping address. Same structure as `billing_address`.
</ResponseField>

<ResponseField name="metadata" type="array | null">
  Custom key/value entries you attached to the customer. Array of `{ key, value }` objects.

  <Expandable title="metadata[]">
    <ResponseField name="key" type="string" required>
      Metadata entry key.
    </ResponseField>

    <ResponseField name="value" type="string" required>
      Metadata entry value.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  Server-generated ISO 8601 timestamp of when the customer record was created.

  Example: `2026-03-01T10:00:00.000000Z`
</ResponseField>

<ResponseField name="updated_at" type="string">
  Server-generated ISO 8601 timestamp of the last update to the customer record.

  Example: `2026-03-01T10:00:00.000000Z`
</ResponseField>

## Example

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "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"
}
```

## Document requirements by country

The `document` object is optional at the schema level, but most Latin American APMs reject the eventual payment if it is missing or has the wrong type for the country.

| Country   | Common payment methods      | Document type                            | Format                   |
| --------- | --------------------------- | ---------------------------------------- | ------------------------ |
| Brazil    | PIX, Boleto, Card           | `CPF` (individuals), `CNPJ` (businesses) | 11 digits / 14 digits    |
| Colombia  | PSE, Nequi, Card            | `CC`, `CE`, `NIT`, `PP`, `TI`            | Varies                   |
| Mexico    | OXXO, SPEI, Card            | `CURP`, `RFC`                            | 18 chars / 12-13 chars   |
| Argentina | Card, Pago Fácil, Rapipago  | `DNI`, `CUIT`, `CUIL`                    | 7-8 / 11 digits          |
| Chile     | Webpay, Bank Transfer, Card | `RUT`, `RUN`                             | 8-9 digits + check digit |
| Peru      | PagoEfectivo, Card          | `DNI`, `RUC`                             | 8 digits / 11 digits     |
| Uruguay   | Card, Redpagos              | `CI`, `RUT`                              | Varies                   |

## Related endpoints

* [Create Customer](/api-reference/customers/create). `POST /v1/customers`
* [Get Customer](/api-reference/customers/get). `GET /v1/customers/{customer_id}`
* [Retrieve Customer by External ID](/api-reference/customers/get-by-external-id). `GET /v1/customers/merchant-customer-id/{merchant_customer_id}`
* [List Customers](/api-reference/customers/list). `GET /v1/customers`
* [Update Customer](/api-reference/customers/update). `PATCH /v1/customers/{customer_id}`
* [Delete Customer](/api-reference/customers/delete). `DELETE /v1/customers/{customer_id}`

## Related concepts

* [Customers](/core-concepts/customers). How customers work in Yuno
* [Tokens](/core-concepts/tokens). How customer tokens and vaulting work
* [Country Reference](/reference/country-reference). Document types and address requirements per country