commercetools Change History API

openapi: 3.2.0
info:
  title: commercetools Change History API
  description: The commercetools Change History API provides a queryable audit log of all changes made to resources within a Composable Commerce project.
  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: Change History
  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:
      - Change History
      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:
      - Change History
      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:
  responses:
    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
    Unauthorized:
      description: The request lacked valid authentication credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
  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.
    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.
    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').
  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