> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a customer

> Replaces the customer's `metadata` with the object you send and returns the updated customer. Fintoc removes the keys you omit and ignores every other field in the body. Only customers created in the `live` or `test` mode of the API key used are visible. Updating a customer from the other mode returns a `404 Not Found` error.



## OpenAPI

````yaml reference/main-api.json PATCH /v2/customers/{id}
openapi: 3.1.0
info:
  title: fintoc-api
  version: v2026-02-01
servers:
  - url: https://api.fintoc.com
security: []
paths:
  /v2/customers/{id}:
    patch:
      tags:
        - Customers
      summary: Update a customer
      description: >-
        Replaces the customer's `metadata` with the object you send and returns
        the updated customer. Fintoc removes the keys you omit and ignores every
        other field in the body. Only customers created in the `live` or `test`
        mode of the API key used are visible. Updating a customer from the other
        mode returns a `404 Not Found` error.
      operationId: v2.customers-update
      parameters:
        - name: id
          in: path
          schema:
            type: string
          description: Unique identifier of the customer to update.
          required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  type: object
                  description: >-
                    Set of key-value pairs that replaces the customer's current
                    `metadata`. Up to 50 keys, each with a non-empty name of up
                    to 40 characters. Each value is a string of up to 500
                    characters, a number, a boolean, or `null`. Send `{}` to
                    remove all keys.
                  example:
                    channel: digital
              required:
                - metadata
            examples:
              update_customer_metadata:
                summary: Record the latest subscription channel
                value:
                  metadata:
                    channel: digital
      responses:
        '200':
          description: The customer with updated `metadata`.
          content:
            application/json:
              examples:
                customer_updated:
                  value:
                    id: cus_0ujsswThIGTUYm2K8FjOOfXtY1K
                    object: customer
                    address:
                      city: Santiago
                      country: cl
                      line1: Av. Providencia 123
                      line2: Depto 45
                      postal_code: '7500000'
                      state: RM
                    created_at: '2026-01-15T14:30:00Z'
                    email: jared@piedpiper.com
                    metadata:
                      channel: digital
                    mode: live
                    name: Test Customer 1
                    phone: '+56911111111'
                    tax_id:
                      type: cl_rut
                      value: '111111111'
              schema:
                $ref: '#/components/schemas/customer'
        '400':
          description: >-
            Invalid request: `metadata` is missing, is not an object, or exceeds
            its format limits.
          content:
            application/json:
              examples:
                missing_metadata:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_parameter
                      message: 'Missing required param: metadata'
                      param: metadata
                      doc_url: https://docs.fintoc.com/reference/errors
                invalid_metadata:
                  value:
                    error:
                      type: invalid_request_error
                      code: invalid_metadata
                      message: Nested json not permitted in Metadata
                      param: metadata
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object_v2'
        '401':
          description: Invalid or missing API key.
          content:
            application/json:
              examples:
                invalid_api_key:
                  value:
                    error:
                      type: authentication_error
                      code: invalid_api_key
                      message: 'Invalid API Key: invalid-*oken'
              schema:
                $ref: '#/components/schemas/error_object'
        '404':
          description: >-
            The customer does not exist, belongs to another organization, or
            belongs to a different mode than the API key.
          content:
            application/json:
              examples:
                customer_not_found:
                  value:
                    error:
                      type: invalid_request_error
                      code: missing_resource
                      param: id
                      message: 'No such customer: cus_0ujsswThIGTUYm2K8FjOOfXtY1K'
                      doc_url: https://docs.fintoc.com/reference/errors
              schema:
                $ref: '#/components/schemas/error_object_v2'
      security:
        - api_key: []
components:
  schemas:
    customer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the customer.
          example: cus_0ujsswThIGTUYm2K8FjOOfXtY1K
        object:
          const: customer
          description: Type of the object. Always `customer`.
        address:
          type:
            - object
            - 'null'
          description: >-
            Customer's address. Only the fields with a value are returned.
            `null` when the customer has no address information.
          properties:
            city:
              type: string
              description: City.
              example: Santiago
            country:
              type: string
              description: Two-letter country code (ISO 3166-1 alpha-2), in lowercase.
              example: cl
            line1:
              type: string
              description: Primary address line.
              example: Av. Providencia 123
            line2:
              type: string
              description: Secondary address line.
              example: Depto 45
            postal_code:
              type: string
              description: Postal or ZIP code.
              example: '7500000'
            state:
              type: string
              description: State or region.
              example: RM
        created_at:
          type: string
          format: date-time
          description: ISO 8601 datetime, in UTC, of when the customer was created.
          example: '2026-01-15T14:30:00Z'
        email:
          type:
            - string
            - 'null'
          description: Customer's email, stored in lowercase. `null` if not provided.
          example: jared@piedpiper.com
        metadata:
          type: object
          description: >-
            Set of key-value pairs that you can attach to an object. Useful for
            storing additional information about the object in a structured
            format.
          example:
            order_id: '12345'
        mode:
          type: string
          enum:
            - live
            - test
          description: >-
            Mode of the customer, matching the mode of the API key used to
            create it. One of `live` or `test`.
          example: live
        name:
          type:
            - string
            - 'null'
          description: Customer's full name or business name. `null` if not provided.
          example: Test Customer 1
        phone:
          type:
            - string
            - 'null'
          description: >-
            Customer's phone number in E.164 format, including the country code
            (for example `+56911111111`). `null` if not provided.
          example: '+56911111111'
        tax_id:
          type:
            - object
            - 'null'
          description: >-
            Tax identifier of the customer: a Chilean tax ID (RUT), a Mexican
            tax ID (RFC), or a custom identifier. `null` if not provided.
          properties:
            type:
              type: string
              enum:
                - cl_rut
                - mx_rfc
                - custom
              description: >-
                Format of the tax identifier. One of `cl_rut` (Chilean tax ID),
                `mx_rfc` (Mexican tax ID), or `custom` (any other identifier).
              example: cl_rut
            value:
              type: string
              description: >-
                Tax identifier, normalized. Fintoc stores RUTs without dots or
                hyphens, RFCs in uppercase, and custom identifiers without
                leading or trailing spaces.
              example: '111111111'
          required:
            - type
            - value
      required:
        - id
        - object
        - address
        - created_at
        - email
        - metadata
        - mode
        - name
        - phone
        - tax_id
    error_object_v2:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
    error_object:
      type: object
      properties:
        error:
          type: object
          description: Details of the error that caused the request to fail.
          properties:
            code:
              type: string
              description: >-
                Machine-readable code identifying the specific error, for
                example `invalid_api_key`. Not returned by every error.
              example: invalid_api_key
            doc_url:
              type: string
              description: >-
                URL of a documentation page with more details about the error.
                Not returned by every error.
              example: https://docs.fintoc.com/reference/errors
            message:
              type: string
              description: Human-readable message describing the error.
              example: 'Invalid API Key: invalid-*oken'
            param:
              type:
                - string
                - 'null'
              description: >-
                Name of the request parameter that caused the error. `null` when
                the error cannot be tied to a single parameter, and not returned
                by every error.
              example: amount
            type:
              type: string
              description: >-
                Category of the error, for example `invalid_request_error`,
                `authentication_error`, or `api_error`.
              example: invalid_request_error
          required:
            - type
            - message
  securitySchemes:
    api_key:
      type: apiKey
      name: Authorization
      in: header

````