commercetools Products API

openapi: 3.1.0
info:
  title: commercetools Change History Carts Products 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: Products
  description: Manage product catalog entries including variants, images, prices, and attributes.
paths:
  /{projectKey}/products:
    get:
      operationId: listProducts
      summary: List products
      description: Returns a paginated list of all products in the project. Supports filtering, sorting, and field expansion via query parameters. Use the Product Projections endpoint for storefront display queries.
      tags:
      - Products
      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 products.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductPagedQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProduct
      summary: Create a product
      description: Creates a new product with the given draft. The product type reference in the draft determines which attributes are valid. The product is created with a staged version and requires publication to become visible in product projections.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/projectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductDraft'
      responses:
        '201':
          description: The created product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{projectKey}/products/{id}:
    get:
      operationId: getProductById
      summary: Get a product by ID
      description: Retrieves a single product by its system-generated ID. The response includes both the current (published) and staged versions of the product data.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateProductById
      summary: Update a product by ID
      description: Applies one or more update actions to the product identified by the given ID. The request must include the current version to enable optimistic concurrency control. Supported actions include changing names, setting attributes, adding variants, and publishing.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductUpdate'
      responses:
        '200':
          description: The updated product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          $ref: '#/components/responses/Conflict'
    delete:
      operationId: deleteProductById
      summary: Delete a product by ID
      description: Permanently deletes the product with the given ID. The current version must be provided as a query parameter for concurrency control. Deletion cannot be undone.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: The deleted product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '409':
          $ref: '#/components/responses/Conflict'
  /{projectKey}/products/import-containers/{importContainerKey}:
    post:
      operationId: importProducts
      summary: Import products
      description: Submits a batch of product import requests to the specified container for asynchronous processing. Each request can contain up to 20 product resources. Products are matched by their user-defined key for upsert behavior.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/projectKey_2'
      - $ref: '#/components/parameters/importContainerKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductImportRequest'
      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:
    ProductData:
      type: object
      description: A version of product data including names, slugs, descriptions, variants, and category assignments.
      required:
      - name
      - slug
      - masterVariant
      - variants
      - categories
      properties:
        name:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        slug:
          $ref: '#/components/schemas/LocalizedString'
        masterVariant:
          $ref: '#/components/schemas/ProductVariant'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariant'
          description: Additional product variants beyond the master variant.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: References to categories this product belongs to.
        metaTitle:
          $ref: '#/components/schemas/LocalizedString'
        metaDescription:
          $ref: '#/components/schemas/LocalizedString'
    PriceDraft:
      type: object
      description: Draft for creating a price on a product variant.
      required:
      - value
      properties:
        value:
          $ref: '#/components/schemas/Money'
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        customerGroup:
          $ref: '#/components/schemas/Reference'
        channel:
          $ref: '#/components/schemas/Reference'
        validFrom:
          type: string
          format: date-time
          description: Start of the validity period for this price.
        validUntil:
          type: string
          format: date-time
          description: End of the validity period for this price.
    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.
    ProductVariantDraft:
      type: object
      description: Draft for creating a product variant.
      properties:
        sku:
          type: string
          description: SKU identifier for the variant.
        key:
          type: string
          description: User-defined unique key for the variant.
        prices:
          type: array
          items:
            $ref: '#/components/schemas/PriceDraft'
          description: Prices to assign to the variant on creation.
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: Product attributes for this variant.
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
          description: Images for the variant.
    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.
    ProductDraft:
      type: object
      description: Request body for creating a new product.
      required:
      - productType
      - name
      - slug
      properties:
        productType:
          $ref: '#/components/schemas/Reference'
        key:
          type: string
          description: User-defined unique key for the product.
        name:
          $ref: '#/components/schemas/LocalizedString'
        slug:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: Categories to assign the product to on creation.
        masterVariant:
          $ref: '#/components/schemas/ProductVariantDraft'
        variants:
          type: array
          items:
            $ref: '#/components/schemas/ProductVariantDraft'
          description: Additional variants to create with the product.
        taxCategory:
          $ref: '#/components/schemas/Reference'
        publish:
          type: boolean
          description: If true, immediately publishes the product after creation.
    Product:
      type: object
      description: A commercetools product resource containing both the current (published) and staged versions of product data including variants, attributes, and metadata.
      required:
      - id
      - version
      - productType
      - masterData
      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.
        productType:
          $ref: '#/components/schemas/Reference'
        masterData:
          $ref: '#/components/schemas/ProductCatalogData'
        taxCategory:
          $ref: '#/components/schemas/Reference'
        state:
          $ref: '#/components/schemas/Reference'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the product was created.
        lastModifiedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the product was last modified.
    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.
    ProductImportRequest:
      type: object
      description: A batch of product resources to import into the project.
      required:
      - type
      - resources
      properties:
        type:
          type: string
          enum:
          - product
          description: The resource type identifier for this import request.
        resources:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/ProductImport'
          description: Up to 20 product resources to import.
    ProductImport:
      type: object
      description: A single product resource for import, matched by key for upsert behavior.
      required:
      - key
      - productType
      - name
      - slug
      properties:
        key:
          type: string
          description: User-defined key for matching against existing products.
        productType:
          type: object
          description: Reference to the product type by key.
        name:
          type: object
          description: Localized name of the product.
        slug:
          type: object
          description: Localized URL-friendly slug for the product.
        description:
          type: object
          description: Localized description of the product.
        categories:
          type: array
          items:
            type: object
          description: Category references by key.
        publish:
          type: boolean
          description: Whether to publish the product after import.
    ProductCatalogData:
      type: object
      description: Container for current (published) and staged product data.
      required:
      - published
      - hasStagedChanges
      properties:
        published:
          type: boolean
          description: Whether the product has a published (current) version.
        current:
          $ref: '#/components/schemas/ProductData'
        staged:
          $ref: '#/components/schemas/ProductData'
        hasStagedChanges:
          type: boolean
          description: Whether there are unpublished staged changes.
    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.
    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
    ProductUpdate:
      type: object
      description: Request body for updating a product using versioned update actions.
      required:
      - version
      - actions
      properties:
        version:
          type: integer
          description: Current version of the product for optimistic concurrency control.
        actions:
          type: array
          items:
            type: object
            description: An update action object with an 'action' discriminator field.
          description: List of update actions to apply to the product.
    ProductPagedQueryResponse:
      type: object
      description: Paginated response containing a list of products.
      required:
      - limit
      - offset
      - count
      - total
      - results
      properties:
        limit:
          type: integer
          description: Maximum number of results returned.
        offset:
          type: integer
          description: Number of results skipped.
        count:
          type: integer
          description: Number of results in this page.
        total:
          type: integer
          description: Total number of matching results.
        results:
          type: array
          items:
            $ref: '#/components/schemas/Product'
          description: The products on this page.
  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.
    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.
    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.
  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
    Conflict:
      description: A version conflict occurred. The provided version does not match the current version of the resource.
      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