commercetools Customers API

openapi: 3.1.0
info:
  title: commercetools Change History Carts Customers API
  description: The commercetools Change History API provides a queryable audit log of all changes made to resources within a Composable Commerce project. It records mutations applied to resources such as products, orders, customers, discounts, and carts, along with metadata about who made the change and when. The API is hosted on separate regional endpoints from the main HTTP API and supports filtering by resource type, date range, user, and API client. It is useful for compliance workflows, debugging unexpected state changes, and building audit trails for regulated industries.
  version: '1.0'
  contact:
    name: commercetools Support
    url: https://support.commercetools.com
  termsOfService: https://commercetools.com/terms-conditions
servers:
- url: https://history.{region}.commercetools.com
  description: Production Change History Server
  variables:
    region:
      default: us-central1.gcp
      enum:
      - us-central1.gcp
      - us-east-2.aws
      - europe-west1.gcp
      - eu-central-1.aws
      - australia-southeast1.gcp
      description: The deployment region.
security:
- bearerAuth: []
tags:
- name: Customers
  description: Manage customer accounts, addresses, authentication, and group assignments.
paths:
  /{projectKey}/customers:
    get:
      operationId: listCustomers
      summary: List customers
      description: Returns a paginated list of all customers in the project. Supports filtering by email, customer group, and other predicates. For large customer bases use the Customer Search endpoint for improved performance.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/sortQuery'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A paged list of customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerPagedQueryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCustomer
      summary: Create a customer
      description: Creates a new customer account. The email address must be unique within the project (or store if store-scoped). Optionally assigns the customer to a customer group and pre-verifies the email address.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/projectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerDraft'
      responses:
        '201':
          description: The created customer sign-in result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerSignInResult'
        '400':
          $ref: '#/components/responses/BadRequest'
  /{projectKey}/customers/{id}:
    get:
      operationId: getCustomerById
      summary: Get a customer by ID
      description: Retrieves a single customer by their system-generated ID, including addresses, customer group assignments, store assignments, and custom fields.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateCustomerById
      summary: Update a customer by ID
      description: Applies update actions to the customer with the given ID. Supported actions include adding addresses, changing email, setting customer group, adding store assignments, and setting custom fields.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerUpdate'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    delete:
      operationId: deleteCustomerById
      summary: Delete a customer by ID
      description: Permanently deletes the customer with the given ID. The current version must be provided. Associated carts, orders, and payment records are not deleted.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: The deleted customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /{projectKey}/customers/import-containers/{importContainerKey}:
    post:
      operationId: importCustomers
      summary: Import customers
      description: Submits a batch of customer import requests for asynchronous processing. Customers are matched by key for upsert behavior. Each request accepts up to 20 customer resources.
      tags:
      - Customers
      parameters:
      - $ref: '#/components/parameters/projectKey_2'
      - $ref: '#/components/parameters/importContainerKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerImportRequest'
      responses:
        '201':
          description: The import request was accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          $ref: '#/components/responses/BadRequest_2'
components:
  schemas:
    Address:
      type: object
      description: A postal address with country and optional structured fields.
      required:
      - country
      properties:
        id:
          type: string
          description: Unique identifier for the address within the resource.
        key:
          type: string
          description: User-defined identifier for the address.
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        firstName:
          type: string
          description: First name of the address recipient.
        lastName:
          type: string
          description: Last name of the address recipient.
        streetName:
          type: string
          description: Street name component of the address.
        streetNumber:
          type: string
          description: Street number component of the address.
        city:
          type: string
          description: City of the address.
        postalCode:
          type: string
          description: Postal or ZIP code of the address.
        region:
          type: string
          description: Region, state, or province of the address.
        email:
          type: string
          format: email
          description: Email address associated with this postal address.
        phone:
          type: string
          description: Phone number associated with this postal address.
    CustomerSignInResult:
      type: object
      description: The result of a customer creation or sign-in operation, including the customer and any merged cart.
      required:
      - customer
      properties:
        customer:
          $ref: '#/components/schemas/Customer'
        cart:
          $ref: '#/components/schemas/Cart'
    Customer:
      type: object
      description: A customer account with authentication credentials, addresses, and commerce profile data.
      required:
      - id
      - version
      - email
      - isEmailVerified
      - addresses
      properties:
        id:
          type: string
          description: System-generated unique identifier.
        version:
          type: integer
          description: Current version for optimistic concurrency control.
        key:
          type: string
          description: User-defined unique identifier.
        email:
          type: string
          format: email
          description: Customer email address, unique within the project or store.
        firstName:
          type: string
          description: Customer first name.
        lastName:
          type: string
          description: Customer last name.
        isEmailVerified:
          type: boolean
          description: Whether the customer email has been verified.
        customerGroup:
          $ref: '#/components/schemas/Reference'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: Saved addresses for the customer.
        stores:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: Stores the customer is assigned to.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the customer was created.
        lastModifiedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the customer was last modified.
    Price:
      type: object
      description: A price entry for a product variant with optional scoping by channel, customer group, country, or validity period.
      required:
      - id
      - value
      properties:
        id:
          type: string
          description: System-generated unique identifier for the price.
        value:
          $ref: '#/components/schemas/Money'
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code to scope the price geographically.
        customerGroup:
          $ref: '#/components/schemas/Reference'
        channel:
          $ref: '#/components/schemas/Reference'
        validFrom:
          type: string
          format: date-time
          description: Start of the price validity period.
        validUntil:
          type: string
          format: date-time
          description: End of the price validity period.
    Money:
      type: object
      description: A monetary value with currency code and amount in the smallest currency unit.
      required:
      - currencyCode
      - centAmount
      properties:
        currencyCode:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 three-letter currency code (e.g., USD, EUR).
        centAmount:
          type: integer
          description: The amount in the smallest indivisible unit of the currency.
        fractionDigits:
          type: integer
          description: Number of fraction digits for the currency. Defaults to 2.
    ErrorObject:
      type: object
      description: An error object describing a validation or processing failure.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable description of the error.
    Reference:
      type: object
      description: A reference to another resource by its typeId and id.
      required:
      - typeId
      - id
      properties:
        typeId:
          type: string
          description: The type identifier of the referenced resource (e.g., 'product', 'category').
        id:
          type: string
          description: The system-generated unique identifier of the referenced resource.
    CustomerUpdate:
      type: object
      description: Request body for updating a customer.
      required:
      - version
      - actions
      properties:
        version:
          type: integer
          description: Current version for optimistic concurrency control.
        actions:
          type: array
          items:
            type: object
          description: List of update actions to apply to the customer.
    ProductVariant:
      type: object
      description: A product variant with SKU, attributes, prices, and images.
      required:
      - id
      properties:
        id:
          type: integer
          description: Variant ID unique within the product (starting at 1 for master).
        sku:
          type: string
          description: Stock keeping unit identifier for this variant.
        key:
          type: string
          description: User-defined unique key for the variant.
        prices:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          description: List of prices for different currencies, channels, and customer groups.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: Product attributes as defined by the product type.
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
          description: List of images for this variant.
    Image:
      type: object
      description: A product image with URL, dimensions, and optional label.
      required:
      - url
      - dimensions
      properties:
        url:
          type: string
          format: uri
          description: URL of the image.
        dimensions:
          type: object
          description: Pixel dimensions of the image.
          required:
          - w
          - h
          properties:
            w:
              type: integer
              description: Image width in pixels.
            h:
              type: integer
              description: Image height in pixels.
        label:
          type: string
          description: Optional label for the image.
    CustomerImport:
      type: object
      description: A single customer resource for import.
      required:
      - key
      - email
      properties:
        key:
          type: string
          description: User-defined key for matching against existing customers.
        email:
          type: string
          format: email
          description: Email address of the customer.
        firstName:
          type: string
          description: First name of the customer.
        lastName:
          type: string
          description: Last name of the customer.
        customerGroup:
          type: object
          description: Reference to customer group by key.
        addresses:
          type: array
          items:
            type: object
          description: Addresses for the customer.
        isEmailVerified:
          type: boolean
          description: Whether the email address is verified.
    Attribute:
      type: object
      description: A name-value pair representing a product attribute as defined by the product type.
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Attribute name as defined in the product type.
        value:
          description: Attribute value. Type depends on the attribute type definition.
    CustomerPagedQueryResponse:
      type: object
      description: Paginated response containing a list of customers.
      required:
      - limit
      - offset
      - count
      - total
      - results
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
        total:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
    LineItem:
      type: object
      description: A product line item in a cart or order with quantity, pricing, and discount information.
      required:
      - id
      - productId
      - name
      - variant
      - price
      - totalPrice
      - quantity
      - lineItemMode
      - priceMode
      properties:
        id:
          type: string
          description: Unique identifier for the line item within the cart.
        productId:
          type: string
          description: ID of the product this line item references.
        name:
          $ref: '#/components/schemas/LocalizedString'
        variant:
          $ref: '#/components/schemas/ProductVariant'
        price:
          $ref: '#/components/schemas/Price'
        totalPrice:
          $ref: '#/components/schemas/Money'
        quantity:
          type: integer
          minimum: 1
          description: Quantity of this product variant in the cart.
        lineItemMode:
          type: string
          enum:
          - Standard
          - GiftLineItem
          description: Whether this is a standard or gift line item.
        priceMode:
          type: string
          enum:
          - Platform
          - ExternalTotal
          - ExternalPrice
          description: How the price for this line item is determined.
    ImportResponse:
      type: object
      description: The response returned after submitting an import request batch.
      required:
      - operationStatus
      properties:
        operationStatus:
          type: array
          items:
            $ref: '#/components/schemas/ImportOperationStatus'
          description: Status records for each resource in the submitted batch.
    ImportOperationStatus:
      type: object
      description: The initial status of a single resource submission in an import batch.
      required:
      - resourceKey
      - state
      properties:
        resourceKey:
          type: string
          description: User-defined key of the resource submitted.
        state:
          type: string
          enum:
          - Accepted
          - ValidationFailed
          description: Initial state of the operation after submission.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: Immediate validation errors if the resource failed submission.
    CustomerImportRequest:
      type: object
      description: A batch of customer resources to import.
      required:
      - type
      - resources
      properties:
        type:
          type: string
          enum:
          - customer
          description: The resource type identifier.
        resources:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/CustomerImport'
          description: Up to 20 customer resources.
    LocalizedString:
      type: object
      description: A map of locale keys to string values used for multilingual content. Keys follow IETF language tag format (e.g., 'en', 'de', 'en-US').
      additionalProperties:
        type: string
    Cart:
      type: object
      description: A shopping cart resource containing line items, discounts, shipping configuration, and pricing.
      required:
      - id
      - version
      - cartState
      - lineItems
      - customLineItems
      - totalPrice
      properties:
        id:
          type: string
          description: System-generated unique identifier.
        version:
          type: integer
          description: Current version for optimistic concurrency control.
        key:
          type: string
          description: User-defined unique identifier.
        customerId:
          type: string
          description: ID of the customer who owns this cart.
        customerEmail:
          type: string
          format: email
          description: Email of the customer associated with this cart.
        cartState:
          type: string
          enum:
          - Active
          - Merged
          - Ordered
          - Frozen
          description: Current state of the cart lifecycle.
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
          description: Product line items in the cart.
        customLineItems:
          type: array
          items:
            type: object
          description: Custom line items with user-defined pricing.
        totalPrice:
          $ref: '#/components/schemas/Money'
        taxedPrice:
          type: object
          description: The total price with tax breakdown if tax calculation is complete.
        billingAddress:
          $ref: '#/components/schemas/Address'
        shippingAddress:
          $ref: '#/components/schemas/Address'
        taxMode:
          type: string
          enum:
          - Platform
          - External
          - ExternalAmount
          - Disabled
          description: Tax calculation mode for this cart.
        inventoryMode:
          type: string
          enum:
          - None
          - TrackOnly
          - ReserveOnOrder
          description: Inventory tracking mode for line items.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the cart was created.
        lastModifiedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the cart was last modified.
    CustomerDraft:
      type: object
      description: Request body for creating a new customer.
      required:
      - email
      - password
      properties:
        key:
          type: string
          description: User-defined unique identifier.
        email:
          type: string
          format: email
          description: Email address for the new customer.
        password:
          type: string
          description: Password for the new customer account.
        firstName:
          type: string
          description: Customer first name.
        lastName:
          type: string
          description: Customer last name.
        customerGroup:
          $ref: '#/components/schemas/Reference'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
          description: Initial addresses for the customer.
        isEmailVerified:
          type: boolean
          description: Whether to pre-verify the email address.
  parameters:
    sortQuery:
      name: sort
      in: query
      required: false
      schema:
        type: string
      description: Sort expression string (e.g., 'createdAt desc'). Multiple sort expressions can be provided as separate parameters.
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 20
      description: Maximum number of results to return. Defaults to 20, maximum 500.
    projectKey:
      name: projectKey
      in: path
      required: true
      schema:
        type: string
      description: The unique key identifying the commercetools project.
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The system-generated unique identifier of the resource.
    where:
      name: where
      in: query
      required: false
      schema:
        type: string
      description: Query predicate string for filtering results. Uses commercetools predicate syntax (e.g., 'customerEmail = "user@example.com"').
    importContainerKey:
      name: importContainerKey
      in: path
      required: true
      schema:
        type: string
      description: The user-defined key of the import container.
    projectKey_2:
      name: projectKey
      in: path
      required: true
      schema:
        type: string
      description: The unique key of the commercetools project.
    expand:
      name: expand
      in: query
      required: false
      schema:
        type: string
      description: Reference expansion path to inline referenced resources in the response (e.g., 'productType', 'categories[*]').
    version:
      name: version
      in: query
      required: true
      schema:
        type: integer
        minimum: 1
      description: Current version of the resource for optimistic concurrency control.
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
      description: Number of results to skip for pagination. Maximum 10000.
  responses:
    BadRequest_2:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
    Unauthorized:
      description: The request lacked valid authentication credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token obtained from the commercetools authentication service using client credentials flow. Requires the view_audit_log scope.
externalDocs:
  description: commercetools Change History API Documentation
  url: https://docs.commercetools.com/api/history/overview