> ## Documentation Index
> Fetch the complete documentation index at: https://redo-44af351d-docs-return-item-identifiers-endpoint.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update customer

> Create or update a customer profile. Uses the email address as the upsert
key — if a customer with that email exists, their profile is updated;
otherwise, a new customer is created.

## Profile fields
- `firstName` and `lastName` are set directly on the customer. A full
  display name is automatically generated from these fields.
- `phoneNumber` should be in E.164 format (e.g., `+12345678900`). If the
  number is new, it is added to the customer's contact information.

## Location
Providing `location` sets the customer's current location. Only the fields
you include are updated.

## Custom fields
Use `customFields` to store arbitrary key-value data on the customer (e.g.,
`pricing_plan`, `subscription_source`). Values can be strings, numbers, or
booleans. If a custom field doesn't exist yet, it is created automatically.




## OpenAPI

````yaml /api-schema/openapi.yaml put /stores/{storeId}/customers
openapi: 3.1.0
info:
  contact:
    email: engineering-admin@getredo.com
    name: Redo Engineering
  description: |
    ## Endpoints

    Endpoints are authenticated using the Bearer authorization scheme, using the
    REDO_API_SECRET.

    ```txt
    GET /v2.2/resource HTTP/1.1
    Authorization: Bearer 77bb7598b7a972475cc7c7e171ec33af
    Host: api.getredo.com
    ```

    ## Webhooks

    Webhooks are authenticated using the Bearer authorization scheme, using
    a secret supplied by the subscriber.

    ```txt
    POST /events HTTP/1.1
    Authorization: Bearer subscriberauth123
    Host: subscriber.example.com
    ```

    Webhook events are delivered in order for each individual subject (e.g.
    return).

    If the response is not a 2xx status code, the event will be retried multiple
    times before discarding it.
  title: Redo API
  version: 2.2.1
servers:
  - url: https://api.getredo.com/v2.2
security: []
tags:
  - name: Checkout Buttons
  - name: Coverage Info
  - name: Coverage Products
  - name: Custom Events
  - name: Customer Portal
  - name: Customer Subscriptions
  - name: Customers
  - name: Inbound Shipments
  - name: Inventory Items
  - name: Inventory Levels
  - name: Invoices
  - name: Merchant Admin
  - name: Orders
  - name: Products
  - name: Returns
  - name: Storefront
  - name: Webhooks
paths:
  /stores/{storeId}/customers:
    summary: Customers
    description: Manage customer profiles.
    put:
      tags:
        - Customers
      summary: Create or update customer
      description: >
        Create or update a customer profile. Uses the email address as the
        upsert

        key — if a customer with that email exists, their profile is updated;

        otherwise, a new customer is created.


        ## Profile fields

        - `firstName` and `lastName` are set directly on the customer. A full
          display name is automatically generated from these fields.
        - `phoneNumber` should be in E.164 format (e.g., `+12345678900`). If the
          number is new, it is added to the customer's contact information.

        ## Location

        Providing `location` sets the customer's current location. Only the
        fields

        you include are updated.


        ## Custom fields

        Use `customFields` to store arbitrary key-value data on the customer
        (e.g.,

        `pricing_plan`, `subscription_source`). Values can be strings, numbers,
        or

        booleans. If a custom field doesn't exist yet, it is created
        automatically.
      operationId: Customer upsert
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer-upsert-request.schema'
            examples:
              create_customer:
                summary: Create a new customer with custom fields
                value:
                  email: jane@example.com
                  firstName: Jane
                  lastName: Smith
                  phoneNumber: '+11234567890'
                  location:
                    street1: 123 Main St
                    street2: Suite 12
                    city: Seattle
                    state: Washington
                    stateCode: WA
                    postalCode: '98101'
                    country: United States
                    countryCode: US
                    latitude: 47.6062
                    longitude: -122.3321
                  customFields:
                    pricing_plan: com.example.yearly
                    status: Active
                    subscription_source: web
                    loyalty_points: 1250
                    vip_member: true
              update_custom_fields:
                summary: Update only custom fields for an existing customer
                value:
                  email: jane@example.com
                  customFields:
                    status: Cancelled
                    cancellation_reason: Too expensive
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-upsert-response.schema'
              example:
                id: 67bd4f1a2e3c8d001a5f9b12
                email: jane@example.com
                created: false
          description: Existing customer updated
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-upsert-response.schema'
              example:
                id: 67bd4f1a2e3c8d001a5f9b12
                email: jane@example.com
                created: true
          description: New customer created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body or invalid email address
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Internal server error
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
components:
  parameters:
    store-id.param:
      description: Store ID
      in: path
      name: storeId
      required: true
      schema:
        example: 64e5a8a1af49a89df37e4ee7
        type: string
  schemas:
    customer-upsert-request.schema:
      additionalProperties: false
      description: >-
        Request body for creating or updating a customer profile. The email
        address is used as the upsert key.
      properties:
        email:
          description: >-
            Customer email address. Used as the upsert key to find or create the
            customer.
          format: email
          type: string
        firstName:
          description: Customer first name
          type: string
        lastName:
          description: Customer last name
          type: string
        phoneNumber:
          description: >-
            Customer phone number in E.164 format (e.g., +12345678900). Appended
            to the existing phone list if not already present.
          examples:
            - '+12345678900'
          type: string
        location:
          $ref: '#/components/schemas/customer-location.schema'
        customFields:
          description: >-
            Custom field values as key-value pairs. Keys are field names and
            values can be strings, numbers, or booleans. The field type is
            determined automatically based on the value:

            - String values → STRING custom field

            - Number values → NUMBER custom field

            - Boolean values → BOOLEAN custom field

            - ISO 8601 datetime strings (e.g., "2026-02-24T12:15:00.000Z") →
            DATE custom field (auto-detected)


            If a field name does not already have a declaration, one is created
            automatically. For STRING fields, unique values are tracked as
            options (used for segment filtering dropdowns). NUMBER, BOOLEAN, and
            DATE fields do not track options.
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
          example:
            subscription_source: web
            status: Active
            loyalty_points: 1250
            vip_member: true
            signup_date: '2026-02-24T12:15:00.000Z'
      required:
        - email
      title: Customer Upsert Request
      type: object
    customer-upsert-response.schema:
      additionalProperties: false
      description: Response after creating or updating a customer profile.
      properties:
        id:
          description: Redo customer ID
          type: string
        email:
          description: Customer email address
          type: string
        created:
          description: >-
            Whether a new customer was created (true) or an existing customer
            was updated (false).
          type: boolean
      required:
        - id
        - email
        - created
      title: Customer Upsert Response
      type: object
    error.schema:
      description: >-
        Problem details. See [RFC 7807 Section
        3](https://datatracker.ietf.org/doc/html/rfc7807#section-3).
      properties:
        detail:
          description: Human-readable description of the problem.
          title: Detail
          type: string
        instance:
          description: A URI reference that identifies this problem.
          format: uri-reference
          type: string
        title:
          description: Human-readable summary of the problem type.
          title: Title
          type: string
        type:
          default: about:blank
          description: A URI reference that identifies the problem type.
          format: uri-reference
          type: string
      title: Problem details
      type: object
    customer-location.schema:
      description: Customer location information.
      properties:
        street1:
          description: Street address line 1
          type: string
        street2:
          description: Street address line 2
          type: string
        city:
          description: City name
          type: string
        state:
          description: State or province name
          examples:
            - Washington
            - Ontario
          type: string
        stateCode:
          description: State or province abbreviation
          examples:
            - WA
            - 'ON'
          type: string
        postalCode:
          description: Postal or ZIP code
          examples:
            - '12345'
            - K1A 0B1
          type: string
        country:
          description: Country name
          examples:
            - United States
            - Canada
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 country code
          examples:
            - US
            - CA
          type: string
        ianaTimeZoneName:
          description: IANA time zone identifier
          examples:
            - America/New_York
            - America/Los_Angeles
          type: string
        latitude:
          description: Latitude coordinate
          type: number
        longitude:
          description: Longitude coordinate
          type: number
      title: Customer Location
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http

````