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

# Get Customer

> Retrieves a customer by ID.



## OpenAPI

````yaml GET /v1/customers/{customer_id}
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/{customer_id}:
    get:
      tags:
        - Customers
      summary: Get customer
      description: Retrieves a customer by ID.
      operationId: getCustomer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: The unique identifier of the customer
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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)

````