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

# Upsert Customer

> Upsert a customer, identified using the customer's `external_id`.



## OpenAPI

````yaml put /customers
openapi: 3.1.0
info:
  title: Customers API
  description: >-
    API for managing customers


    ### Resource identifier format


    Resource identifiers (the `id` field and related global-identifier fields)
    are returned as JSON

    integers by default. To receive them as strings instead, send the

    `X-Loop-Global-Identifier-Type: string` request header.
  version: v1
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Customers
paths:
  /customers:
    put:
      tags:
        - Customers
      summary: Upsert Customer
      description: Upsert a customer, identified using the customer's `external_id`.
      operationId: upsertCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCustomerRequest'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerWrappedResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
      security:
        - write: []
components:
  schemas:
    UpsertCustomerRequest:
      type: object
      properties:
        external_id:
          type: string
          minLength: 1
          maxLength: 64
          description: The identifier used by an external source to identify the customer.
          examples:
            - 71263csss-12uhsdfh-2138dja
        sales_channel:
          type: string
          maxLength: 255
          examples:
            - shopify
          description: >-
            If a channel with this name is not already associated with the shop,
            it will be used to create a new channel.
        first_name:
          type:
            - string
            - 'null'
          maxLength: 50
          examples:
            - Edgar
          description: The customer's given name.
        last_name:
          type:
            - string
            - 'null'
          maxLength: 50
          examples:
            - Martinez
          description: The customer's surname.
        email:
          type:
            - string
            - 'null'
          maxLength: 255
          description: The customer's email address.
          format: email
          examples:
            - sample@example.com
        phone:
          type:
            - string
            - 'null'
          maxLength: 30
          examples:
            - 678-999-8212
          description: The customer's phone number.
        tags:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/TagRequestData'
          examples:
            - - FirstPurchase
              - ReturnCustomer
          description: An array of tags used to classify and group customers.
      required:
        - external_id
        - sales_channel
    CustomerWrappedResponse:
      type: object
      required:
        - customer
      properties:
        customer:
          $ref: '#/components/schemas/CustomerResponse'
    UnauthorizedResponse:
      type: object
      required:
        - errors
      properties:
        errors:
          type: string
          examples:
            - Unauthorized.
    ValidationErrorResponse:
      type: object
      description: >-
        Returned when the request body fails validation. Uses Laravel's standard
        validation error shape.
      properties:
        message:
          type: string
          examples:
            - The external_id field is required.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          examples:
            - external_id:
                - The external_id field is required.
    TagRequestData:
      description: A tag, accepted either as a plain string or as an object with a `name`.
      oneOf:
        - type: string
          minLength: 1
          maxLength: 255
          description: The tag name, provided as a plain string.
        - type: object
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 255
              description: Name of the tag.
          required:
            - name
    CustomerResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the customer, created by Loop.
          examples:
            - 9007199254740991
        external_id:
          type:
            - string
            - 'null'
          description: The identifier used by an external source to identify the customer.
          examples:
            - 71263csss-12uhsdfh-2138dja
        sales_channel:
          type:
            - string
            - 'null'
          examples:
            - shopify
          description: The name of the channel associated with the customer.
        first_name:
          type:
            - string
            - 'null'
          description: The customer's given name.
          examples:
            - Edgar
        last_name:
          type:
            - string
            - 'null'
          description: The customer's surname.
          examples:
            - Martinez
        email:
          type:
            - string
            - 'null'
          description: The customer's email address.
          format: email
          examples:
            - sample@example.com
        phone:
          type:
            - string
            - 'null'
          description: The customer's phone number.
          examples:
            - 678-999-8212
        tags:
          type: array
          items:
            type: string
          examples:
            - - FirstPurchase
              - ReturnCustomer
          description: An array of tags associated with the customer.
  securitySchemes:
    write:
      name: X-Authorization
      type: apiKey
      in: header
      description: 'API Scope: "Customers (write)"'

````