commercetools ChangeHistory API

openapi: 3.1.0
info:
  title: commercetools Change History Carts ChangeHistory 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: ChangeHistory
  description: Query the audit log of resource changes across the project.
paths:
  /{projectKey}:
    get:
      operationId: listChanges
      summary: Query change history records
      description: Returns a paginated list of change history records for the project. Each record contains a list of individual changes along with metadata about the actor and timestamp. Supports filtering by resource type, date range, resource ID, user, and client.
      tags:
      - ChangeHistory
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - name: date.from
        in: query
        required: false
        schema:
          type: string
        description: Start of the date range filter. Accepts ISO 8601 datetime strings or relative values like "24" (last 24 hours) or "now".
      - name: date.to
        in: query
        required: false
        schema:
          type: string
        description: End of the date range filter. Accepts ISO 8601 datetime strings or relative values like "now".
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 20
        description: Maximum number of records to return per page.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          maximum: 10000
          default: 0
        description: Number of records to skip for pagination.
      - name: resourceTypes
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated list of resource types to filter by (e.g., "order,product,customer").
      - name: changes
        in: query
        required: false
        schema:
          type: string
        description: Filter by specific change type name (e.g., "setCustomField", "changeOrderState").
      - name: resourceId
        in: query
        required: false
        schema:
          type: string
        description: Filter records to changes affecting a specific resource ID.
      - name: userId
        in: query
        required: false
        schema:
          type: string
        description: Filter records to changes made by a specific user ID.
      - name: clientId
        in: query
        required: false
        schema:
          type: string
        description: Filter records to changes made by a specific API client ID.
      responses:
        '200':
          description: A paged list of change history records.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Total rate limit tokens available for the current window.
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Rate limit tokens remaining after this request.
            X-RateLimit-Request-Cost:
              schema:
                type: integer
              description: Number of rate limit tokens consumed by this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordPagedQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /{projectKey}/{resourceType}/{id}:
    get:
      operationId: listChangesByResourceId
      summary: Query change history for a specific resource
      description: Returns a paginated list of change history records filtered to a specific resource type and resource ID. This is the most efficient way to retrieve the full change history of a single resource, such as all changes made to a specific order or product.
      tags:
      - ChangeHistory
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - name: resourceType
        in: path
        required: true
        schema:
          type: string
          enum:
          - associate-roles
          - business-units
          - cart-discounts
          - categories
          - channels
          - customer-groups
          - customers
          - discount-codes
          - inventory-entries
          - key-value-documents
          - orders
          - payments
          - product-discounts
          - product-selections
          - product-types
          - products
          - quote-requests
          - quotes
          - reviews
          - shipping-methods
          - shopping-lists
          - staged-quotes
          - standalone-prices
          - states
          - stores
          - tax-categories
          - types
          - zones
        description: The resource type category to filter the change history query.
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: The system-generated ID of the specific resource.
      - name: date.from
        in: query
        required: false
        schema:
          type: string
        description: Start of the date range filter.
      - name: date.to
        in: query
        required: false
        schema:
          type: string
        description: End of the date range filter.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 20
        description: Maximum number of records to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of records to skip for pagination.
      responses:
        '200':
          description: A paged list of change history records for the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordPagedQueryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    RecordPagedQueryResponse:
      type: object
      description: Paginated response containing a list of change history records.
      required:
      - limit
      - offset
      - count
      - total
      - results
      properties:
        limit:
          type: integer
          description: Maximum number of records returned.
        offset:
          type: integer
          description: Number of records skipped.
        count:
          type: integer
          description: Number of records in this page.
        total:
          type: integer
          description: Total number of matching records.
        results:
          type: array
          items:
            $ref: '#/components/schemas/Record'
          description: The change history records on this page.
    ModifiedBy:
      type: object
      description: Information about the actor who made the change.
      properties:
        id:
          type: string
          description: System-generated ID of the user or client.
        type:
          type: string
          enum:
          - user
          - external-user
          - customer
          - key
          description: The type of actor that made the change.
        clientId:
          type: string
          description: ID of the API client used to make the change.
        anonymousId:
          type: string
          description: Anonymous session ID if the change was made without a customer login.
        customer:
          $ref: '#/components/schemas/Reference'
        isPlatformClient:
          type: boolean
          description: Whether the change was made via the Merchant Center.
    Record:
      type: object
      description: A change history record capturing a set of changes applied to a resource in a single operation, along with actor and timestamp metadata.
      required:
      - id
      - resource
      - resourceType
      - changes
      - createdAt
      properties:
        id:
          type: string
          description: System-generated unique identifier for the record.
        resource:
          $ref: '#/components/schemas/Reference'
        resourceVersion:
          type: integer
          description: The version of the resource after these changes were applied.
        resourceType:
          type: string
          description: The type of resource that was changed.
        changes:
          type: array
          items:
            $ref: '#/components/schemas/Change'
          description: List of individual field-level changes captured in this record.
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the changes were made.
        createdBy:
          $ref: '#/components/schemas/ModifiedBy'
        label:
          type: object
          description: A label identifying the changed resource (e.g., product name, order number).
        previousVersion:
          type: integer
          description: The version of the resource before these changes were applied.
        type:
          type: string
          description: The type of modification (e.g., 'update', 'create', 'delete').
    Change:
      type: object
      description: A single field-level change within a change history record.
      required:
      - change
      - type
      properties:
        change:
          type: string
          description: The name of the update action that caused this change (e.g., 'setCustomField', 'changeOrderState').
        type:
          type: string
          description: The type identifier of this change entry.
        previousValue:
          description: The field value before the change was applied.
        nextValue:
          description: The field value after the change was applied.
    Reference:
      type: object
      description: A reference to another resource by typeId and id.
      required:
      - typeId
      - id
      properties:
        typeId:
          type: string
          description: The type identifier of the referenced resource.
        id:
          type: string
          description: The system-generated unique identifier of the referenced resource.
  responses:
    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
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
  parameters:
    projectKey:
      name: projectKey
      in: path
      required: true
      schema:
        type: string
      description: The unique key of the commercetools project.
  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