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

# Update Customer

> Updates an existing customer's mutable fields such as email, name, phone, or document.



## OpenAPI

````yaml PATCH /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}:
    patch:
      tags:
        - Customers
      summary: Update customer
      description: >-
        Updates an existing customer's mutable fields such as email, name,
        phone, or document.
      operationId: updateCustomer
      parameters:
        - name: customer_id
          in: path
          required: true
          description: The unique identifier of the customer
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerRequest'
            example:
              email: maria.updated@example.com
              phone:
                country_code: '55'
                number: '11888880000'
      responses:
        '200':
          description: Customer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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)

````