Medusa Customers API

openapi: 3.2.0
info:
  title: Medusa Customers API
  version: 2.19.0
  description: 'Operations tagged Customers across 2 of this provider''s published API definitions: medusa-admin-openapi.yaml, medusa-store-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Customers
  description: 'Customers can either be created when they register through the Store APIs, or created by the admin using the Admin APIs.


    These API routes allow admin users to manage customers in their store.

    '
  externalDocs:
    description: Learn more about the Customer Module
    url: https://docs.medusajs.com/resources/commerce-modules/customer
  x-associatedSchema:
    $ref: '#/components/schemas/AdminCustomer'
paths:
  /admin/customers:
    get:
      operationId: GetCustomers
      summary: List Customers
      description: Retrieve a list of customers. The customers can be filtered by fields such as `id`. The customers can also be sorted or paginated.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the [Retrieve Custom Links](https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links) documentation.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields. This API route restricts the fields that can be selected. Learn how to override the retrievable fields in the [Retrieve Custom Links](https://docs.medusajs.com/learn/fundamentals/api-routes/retrieve-custom-links) documentation.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
      - name: groups
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: groups
            description: Filter by a customer group's ID to retrieve customers that belong to it.
          - $ref: '#/components/schemas/CustomerGroupInCustomerFilters'
          - type: array
            description: Filter by customer group IDs to retrieve customers that belong to them.
            items:
              type: string
              title: groups
              description: The customer group's ID.
      - name: q
        in: query
        description: Search term to filter the customer's searchable properties by.
        required: false
        schema:
          type: string
          title: q
          description: Search term to filter the customer's searchable properties by.
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by a customer's ID.
          - type: array
            description: Filter by customer IDs.
            items:
              type: string
              title: id
              description: A customer's ID.
          - type: object
            description: Filters to apply on the customer ID.
            properties:
              $and:
                type: array
                description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
                title: $and
              $or:
                type: array
                description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
                title: $or
              $eq:
                oneOf:
                - type: string
                  title: $eq
                  description: Filter by an exact match.
                - type: array
                  description: Filter by exact matches.
                  items:
                    type: string
                    title: $eq
                    description: Filter by an exact match.
                - type: array
                  description: Filter by exact matches.
                  items:
                    oneOf:
                    - type: string
                      title: $eq
                      description: Filter by an exact match.
                    - type: array
                      description: Filter by exact matches.
                      items:
                        type: string
                        title: $eq
                        description: Filter by an exact match.
              $ne:
                oneOf:
                - type: string
                  title: $ne
                  description: Filter by values not equal to this parameter.
                - type: array
                  description: Filter by values not in this array.
                  items:
                    type: string
                    title: $ne
                    description: Filter by values not equal to this parameter.
              $in:
                type: array
                description: Filter by values in this array.
                items:
                  oneOf:
                  - type: string
                    title: $in
                    description: Filter by matching value.
                  - type: array
                    description: Filter by values in this array.
                    items:
                      type: string
                      title: $in
                      description: Filter matching values.
              $nin:
                type: array
                description: Filter by values not in this array.
                items:
                  oneOf:
                  - type: string
                    title: $nin
                    description: Filter by values not matching this parameter.
                  - type: array
                    description: Filter by values not in this array.
                    items:
                      type: string
                      title: $nin
                      description: Filter by values not matching this parameter.
              $not:
                oneOf:
                - type: string
                  title: $not
                  description: Filter by values not matching this parameter.
                - type: object
                  description: Filter by values not matching the conditions in this parameter.
                  properties:
                    $and:
                      type: array
                      description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                      items:
                        type: object
                      title: $and
                    $or:
                      type: array
                      description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                      items:
                        type: object
                      title: $or
                    $eq:
                      oneOf:
                      - type: string
                        title: $eq
                        description: Filter by an exact match.
                      - type: array
                        description: Filter by exact matches.
                        items:
                          type: string
                          title: $eq
                          description: Filter by an exact match.
                    $ne:
                      type: string
                      title: $ne
                      description: Filter by values not equal to this parameter.
                    $in:
                      type: array
                      description: Filter by values in this array.
                      items:
                        type: string
                        title: $in
                        description: Filter by values in this array.
                    $nin:
                      type: array
                      description: Filter by values not in this array.
                      items:
                        type: string
                        title: $nin
                        description: Filter by values not in this array.
                    $not:
                      oneOf:
                      - type: string
                        title: $not
                        description: Filter by values not matching this parameter.
                      - type: object
                        description: Filter by values not matching the conditions in this parameter.
                      - type: array
                        description: Filter by values not in this array.
                        items:
                          type: string
                          title: $not
                          description: Filter by values not matching this parameter.
                    $gt:
                      type: string
                      title: $gt
                      description: Filter by values greater than this parameter. Useful for numbers and dates only.
                    $gte:
                      type: string
                      title: $gte
                      description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
                    $lt:
                      type: string
                      title: $lt
                      description: Filter by values less than this parameter. Useful for numbers and dates only.
                    $lte:
                      type: string
                      title: $lte
                      description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
                    $like:
                      type: string
                      title: $like
                      description: Apply a `like` filter. Useful for strings only.
                    $re:
                      type: string
                      title: $re
                      description: Apply a regex filter. Useful for strings only.
                    $ilike:
                      type: string
                      title: $ilike
                      description: Apply a case-insensitive `like` filter. Useful for strings only.
                    $fulltext:
                      type: string
                      title: $fulltext
                      description: Filter to apply on full-text properties.
                    $overlap:
                      type: array
                      description: Filter arrays that have overlapping values with this parameter.
                      items:
                        type: string
                        title: $overlap
                        description: Filter arrays that have overlapping values with this parameter.
                    $contains:
                      type: array
                      description: Filter arrays that contain some of the values of this parameter.
                      items:
                        type: string
                        title: $contains
                        description: Filter arrays that contain some of the values of this parameter.
                    $contained:
                      type: array
                      description: Filter arrays that contain all values of this parameter.
                      items:
                        type: string
                        title: $contained
                        description: Filter arrays that contain all values of this parameter.
                    $exists:
                      type: boolean
                      title: $exists
                      description: Filter by whether a value for this parameter exists (not `null`).
                - type: array
                  description: Filter by values not in this array.
                  items:
                    type: string
                    title: $not
                    description: Filter by values not matching this parameter.
                - type: array
                  description: Filter by values not matching the conditions in this parameter.
                  items:
                    oneOf:
                    - type: string
                      title: $not
                      description: Filter by values not matching this parameter.
                    - type: object
                      description: Filter by values not matching the conditions in this parameter.
                      properties:
                        $and:
                          type: array
                          description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                          items:
                            type: object
                          title: $and
                        $or:
                          type: array
                          description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                          items:
                            type: object
                          title: $or
                        $eq:
                          oneOf:
                          - type: string
                            title: $eq
                            description: Filter by an exact match.
                          - type: array
                            description: Filter by exact matches.
                            items:
                              type: string
                              title: $eq
                              description: Filter by an exact match.
                        $ne:
                          type: string
                          title: $ne
                          description: Filter by values not equal to this parameter.
                        $in:
                          type: array
                          description: Filter by values in this array.
                          items:
                            type: string
                            title: $in
                            description: Filter by exact matches.
                        $nin:
                          type: array
                          description: Filter by values not in this array.
                          items:
                            type: string
                            title: $nin
                            description: Filter by values not matching this parameter.
                        $not:
                          oneOf:
                          - type: string
                            title: $not
                            description: Filter by values not matching this parameter.
                          - type: object
                            description: Filter by values not matching the conditions in this parameter.
                          - type: array
                            description: Filter by values not in this array.
                            items:
                              type: string
                              title: $not
                              description: Filter by values not matching this parameter.
                        $gt:
                          type: string
                          title: $gt
                          description: Filter by values greater than this parameter. Useful for numbers and dates only.
                        $gte:
                          type: string
                          title: $gte
                          description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
                        $lt:
                          type: string
                          title: $lt
                          description: Filter by values less than this parameter. Useful for numbers and dates only.
                        $lte:
                          type: string
                          title: $lte
                          description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
                        $like:
                          type: string
                          title: $like
                          description: Apply a `like` filter. Useful for strings only.
                        $re:
                          type: string
                          title: $re
                          description: Apply a regex filter. Useful for strings only.
                        $ilike:
                          type: string
                          title: $ilike
                          description: Apply a case-insensitive `like` filter. Useful for strings only.
                        $fulltext:
                          type: string
                          title: $fulltext
                          description: Filter to apply on full-text properties.
                        $overlap:
                          type: array
                          description: Filter arrays that have overlapping values with this parameter.
                          items:
                            type: string
                            title: $overlap
                            description: Filter arrays that have overlapping values with this parameter.
                        $contains:
                          type: array
                          description: Filter arrays that contain some of the values of this parameter.
                          items:
                            type: string
                            title: $contains
                            description: Filter arrays that contain some of the values of this parameter.
                        $contained:
                          type: array
                          description: Filter arrays that contain all values of this parameter.
                          items:
                            type: string
                            title: $contained
                            description: Filter arrays that contain all values of this parameter.
                        $exists:
                          type: boolean
                          title: $exists
                          description: Filter by whether a value for this parameter exists (not `null`).
              $gt:
                oneOf:
                - type: string
                  title: $gt
                  description: Filter by values greater than this parameter. Useful for numbers and dates only.
                - type: array
                  description: Filter by values greater than items in this array. Useful for numbers and dates only.
                  items:
                    type: string
                    title: $gt
                    description: Filter by values greater than this parameter. Useful for numbers and dates only.
              $gte:
                oneOf:
                - type: string
                  title: $gte
                  description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
                - type: array
                  description: Filter by values greater than or equal to items in this array. Useful for numbers and dates only.
                  items:
                    type: string
                    title: $gte
                    description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
              $lt:
                oneOf:
                - type: string
                  title: $lt
                  description: Filter by values less than this parameter. Useful for numbers and dates only.
                - type: array
                  description: Filter by values less than items in this array. Useful for numbers and dates only.
                  items:
                    type: string
                    title: $lt
                    description: Filter by values less than this parameter. Useful for numbers and dates only.
              $lte:
                oneOf:
                - type: string
                  title: $lte
                  description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
                - type: array
                  description: Filter by values less than or equal to items in this array. Useful for numbers and dates only.
                  items:
                    type: string
                    title: $lte
                    description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
              $like:
                type: string
                title: $like
                description: Apply a `like` filter. Useful for strings only.
              $re:
                type: string
                title: $re
                description: Apply a regex filter. Useful for strings only.
              $ilike:
                type: string
                title: $ilike
                description: Apply a case-insensitive `like` filter. Useful for strings only.
              $fulltext:
                type: string
                title: $fulltext
                description: Filter to apply on full-text properties.
              $overlap:
                type: array
                description: Filter arrays that have overlapping values with this parameter.
                items:
                  type: string
                  title: $overlap
                  description: Filter arrays that have overlapping values with this parameter.
              $contains:
                type: array
                description: Filter arrays that contain some of the values of this parameter.
                items:
                  type: string
                  title: $contains
                  description: Filter arrays that contain some of the values of this parameter.
              $contained:
                type: array
                description: Filter arrays that contain all values of this parameter.
                items:
                  type: string
                  title: $contained
                  description: Filter arrays that contain all values of this parameter.
              $exists:
                type: boolean
                title: $exists
                description: Filter by whether a value for this parameter exists (not `null`).
      - name: email
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: email
            description: Filter by a customer email.
            format: email
          - type: array
            description: Filter by customer emails.
            items:
              type: string
              title: email
              description: A customer's email.
              format: email
          - type: object
            description: Filter by conditions on the customer email.
            properties:
              $and:
                type: array
                description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
                title: $and
              $or:
                type: array
                description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                items:
                  type: object
                title: $or
              $eq:
                oneOf:
                - type: string
                  title: $eq
                  description: Filter by an exact match.
                - type: array
                  description: Filter by exact matches.
                  items:
                    type: string
                    title: $eq
                    description: Filter by an exact match.
                - type: array
                  description: Filter by exact matches.
                  items:
                    oneOf:
                    - type: string
                      title: $eq
                      description: Filter by an exact match.
                    - type: array
                      description: Filter by exact matches.
                      items:
                        type: string
                        title: $eq
                        description: Filter by an exact match.
              $ne:
                oneOf:
                - type: string
                  title: $ne
                  description: Filter by values not equal to this parameter.
                - type: array
                  description: Filter by values not in this array.
                  items:
                    type: string
                    title: $ne
                    description: Filter by values not equal to this parameter.
              $in:
                type: array
                description: Filter by values in this array.
                items:
                  oneOf:
                  - type: string
                    title: $in
                    description: Filter by matching value.
                  - type: array
                    description: Filter by values in this array.
                    items:
                      type: string
                      title: $in
                      description: Filter matching values.
              $nin:
                type: array
                description: Filter by values not in this array.
                items:
                  oneOf:
                  - type: string
                    title: $nin
                    description: Filter by values not matching this parameter.
                  - type: array
                    description: Filter by values not in this array.
                    items:
                      type: string
                      title: $nin
                      description: Filter by values not matching this parameter.
              $not:
                oneOf:
                - type: string
                  title: $not
                  description: Filter by values not matching this parameter.
                - type: object
                  description: Filter by values not matching the conditions in this parameter.
                  properties:
                    $and:
                      type: array
                      description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
                      items:
                        type: object
                      title: $and
                    $or:
                      type: array
                      description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
                      items:
                        type: object
                      title: $or
                    $eq:
                      oneOf:
                      - type: string
                        title: $eq
                        description: Filter by an exact match.
                      - type: array
                        description: Filter by exact matches.
                        items:
                          type: string
                          title: $eq
                          description: Filter by an exact match.
                    $ne:
                      type: string
                      title: $ne
                      description: Filter by values not equal to this parameter.
                    $in:
                      type: array
                      description: Filter by values in this array.
                      items:
                        type: string
                        title: $in
                        description: Filter by values in this array.
                    $nin:
                      type: array
                      description: Filter by values not in this array.
                      items:
                        type: string
                        title: $nin
                        description: Filter by values not in this array.
                    $not:
                      oneOf:
                      - type: string
                        title: $not
                        description: Filter by values not matching this parameter.
                      - type: object
                        description: Filter by values not matching the conditions in this parameter.
                      - type: array
                        description: Filter by values not in this array.
                        items:
                          type: string
                          title: $not
                          description: Filter by values not matching this parameter.
                    $gt:
                      type: string
                      title: $gt
                      description: Filter by values greater than this parameter. Useful for numbers and dates only.
                    $gte:
                      type: string
                      title: $gte
                      description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
                    $lt:
                      type: string
                      title: $lt
                      description: Filter by values less than this parameter. Useful for numbers and dates only.
                    $lte:
                      type: string
                      title: $lte
                      description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
                    $like:
                      type: string
                      title: $like
                      description: Apply a `like` filter. Useful for strings only.
                    $re:
                      type: string
                      title: $re
                      description: Apply a regex filter. Useful for strings only.
                    $ilike:
                      type: string
                      title: $ilike
                      description: Apply a case-insensitive `like` filter. Useful for strings only.
                    $fulltext:
                      type: string
                      title: $fulltext
                      description: Filter to apply on full-text properties.
                    $overlap:
                      type: array
                      description: Filter arrays that have overlapping values with this parameter.
                      items:
                        type: string
                        title: $overlap
                        description: Filter arrays that have overlapping values with this parameter.
                    $contains:
                      type: array
                      description: Filter arrays that contai

# --- truncated at 32 KB (283 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/medusa/refs/heads/main/openapi/medusa-customers-api-openapi.yml