commercetools Categories API

openapi: 3.1.0
info:
  title: commercetools Change History Carts Categories 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: Categories
  description: Organize products into hierarchical category structures.
paths:
  /{projectKey}/categories:
    get:
      operationId: listCategories
      summary: List categories
      description: Returns a paginated list of all categories in the project. Categories can be filtered and sorted using standard query predicates. Use parent references to reconstruct the category hierarchy.
      tags:
      - Categories
      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 categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryPagedQueryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCategory
      summary: Create a category
      description: Creates a new category. Categories support localized names, slugs, and metadata, and can optionally reference a parent category to build a hierarchy.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/projectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryDraft'
      responses:
        '201':
          description: The created category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
  /{projectKey}/categories/{id}:
    get:
      operationId: getCategoryById
      summary: Get a category by ID
      description: Retrieves a single category by its system-generated unique identifier, including its ancestors array representing the full path to the root category.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: updateCategoryById
      summary: Update a category by ID
      description: Applies update actions to the category with the given ID. Supported actions include changing the name, slug, parent, order hint, and custom fields.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryUpdate'
      responses:
        '200':
          description: The updated category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
    delete:
      operationId: deleteCategoryById
      summary: Delete a category by ID
      description: Permanently deletes the category with the given ID. The current version must be provided. Categories with children or product assignments cannot be deleted until those references are removed.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/version'
      responses:
        '200':
          description: The deleted category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
  /{projectKey}/categories/import-containers/{importContainerKey}:
    post:
      operationId: importCategories
      summary: Import categories
      description: Submits a batch of category import requests for asynchronous processing. Categories are matched by key for upsert behavior. Parent category references are resolved after all categories in the batch are processed.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/projectKey_2'
      - $ref: '#/components/parameters/importContainerKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryImportRequest'
      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:
  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
    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
  schemas:
    CategoryImportRequest:
      type: object
      description: A batch of category resources to import.
      required:
      - type
      - resources
      properties:
        type:
          type: string
          enum:
          - category
          description: The resource type identifier.
        resources:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/CategoryImport'
          description: Up to 20 category resources.
    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.
    Category:
      type: object
      description: A category resource for organizing products in a hierarchical structure.
      required:
      - id
      - version
      - name
      - slug
      - ancestors
      - orderHint
      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.
        name:
          $ref: '#/components/schemas/LocalizedString'
        slug:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        parent:
          $ref: '#/components/schemas/Reference'
        ancestors:
          type: array
          items:
            $ref: '#/components/schemas/Reference'
          description: Ordered list of ancestor category references from root to immediate parent.
        orderHint:
          type: string
          description: Decimal string between 0 and 1 for ordering within siblings.
        metaTitle:
          $ref: '#/components/schemas/LocalizedString'
        metaDescription:
          $ref: '#/components/schemas/LocalizedString'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the category was created.
        lastModifiedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the category was last modified.
    CategoryUpdate:
      type: object
      description: Request body for updating a category.
      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.
    CategoryImport:
      type: object
      description: A single category resource for import.
      required:
      - key
      - name
      - slug
      properties:
        key:
          type: string
          description: User-defined key for matching against existing categories.
        name:
          type: object
          description: Localized name of the category.
        slug:
          type: object
          description: Localized URL-friendly slug.
        description:
          type: object
          description: Localized description of the category.
        parent:
          type: object
          description: Reference to parent category by key.
        orderHint:
          type: string
          description: Decimal ordering hint between 0 and 1.
    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.
    CategoryDraft:
      type: object
      description: Request body for creating a new category.
      required:
      - name
      - slug
      properties:
        key:
          type: string
          description: User-defined unique identifier.
        name:
          $ref: '#/components/schemas/LocalizedString'
        slug:
          $ref: '#/components/schemas/LocalizedString'
        description:
          $ref: '#/components/schemas/LocalizedString'
        parent:
          $ref: '#/components/schemas/Reference'
        orderHint:
          type: string
          description: Decimal string between 0 and 1 for ordering within siblings.
        metaTitle:
          $ref: '#/components/schemas/LocalizedString'
        metaDescription:
          $ref: '#/components/schemas/LocalizedString'
    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
    CategoryPagedQueryResponse:
      type: object
      description: Paginated response containing a list of categories.
      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/Category'
  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