Change History

View changes made to resources within a Composable Commerce Project.

Change History is a historical log of changes (create, update, and delete) made to supported entity types within a Project.

The default offering of Audit Log (Audit Log Basic) only tracks changes made in the Merchant Center. With Audit Log Basic, changes originating from other sources, such as APIs, will not show in the query results.

Hosts

The Change History API has different hosts than the HTTP API and is hosted at the following URLs:

Region	API URL
North America (Google Cloud, Iowa)	`https://history.us-central1.gcp.commercetools.com/`
North America (AWS, Ohio)	`https://history.us-east-2.aws.commercetools.com/`
Europe (Google Cloud, Belgium)	`https://history.europe-west1.gcp.commercetools.com/`
Europe (AWS, Frankfurt)	`https://history.eu-central-1.aws.commercetools.com/`
Australia (Google Cloud, Sydney)	`https://history.australia-southeast1.gcp.commercetools.com/`

If the documentation refers to https://history.{region}.commercetools.com, replace the {region} placeholder with the actual value.

Representations

Representations are JSON objects submitted or received as payload to API requests or responses.

Record

Captures the differences between the previous and next version of a resource.

The maximum number of Records that can be stored and their retention period are subject to a limit.

`version` Int	Version of the resource after the change. For more information on how the version is incremented, see Optimistic Concurrency Control.
`previousVersion` Int	Version of the resource before the change.
`type` String	Indicates the type of change. For creation, update, or deletion, the value is `"ResourceCreated"`, `"ResourceUpdated"`, or `"ResourceDeleted"` respectively.
`modifiedBy` ModifiedBy	Information about the user or API Client who performed the change.
`modifiedAt` String	Date and time (UTC) the change was made.
`label` Label	Information that describes the resource after the change.
`previousLabel` Label	Information that describes the resource before the change.
`changes` Array of Change	Shows the differences in the resource between `previousVersion` and `version`. The value is not identical to the actual array of update actions sent and is not limited to update actions (see, for example, Optimistic Concurrency Control).
`resource` ResourceIdentifier	ResourceIdentifier of the changed resource.
`stores` Array of KeyReference	References to the Stores associated with the Change.
`businessUnit` KeyReference	Reference to the Business Unit associated with the Change. Only available for B2B-enabled Projects.
`withoutChanges` Boolean	`true` if no change was detected. The version number of the resource can be increased even without any change in the resource.

Example: json

{
  "version": 2,
  "previousVersion": 1,
  "type": "ResourceUpdated",
  "modifiedAt": "2020-03-22T23:00:00.000Z",
  "modifiedBy": {
    "isPlatformClient": true,
    "id": "example_user_123",
    "type": "user",
    "customer": {
      "id": "test1",
      "typeId": "customer"
    }
  },
  "resource": {
    "id": "some_entity_id_123",
    "typeId": "product",
    "key": "some_entity_key_123"
  },
  "label": {
    "value": "some_label",
    "type": "StringLabel"
  },
  "previousLabel": {
    "value": "some_label",
    "type": "StringLabel"
  },
  "withoutChanges": false,
  "stores": [],
  "businessUnit": {
    "typeId": "business-unit",
    "key": "some_business_unit_key_123"
  },
  "changes": [
    {
      "change": "setKey",
      "previousValue": "Key 1",
      "nextValue": "Key 2",
      "type": "SetKeyChange"
    }
  ]
}

RecordPagedQueryResponse

PagedQueryResult with results containing an array of Record.

`limit` Int	Number of results requested. Default: `20`Minimum: `0`Maximum: `500`
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation and not strongly consistent.
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10000`
`results` Array of Record	Records matching the query.

Example: json

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 0,
  "results": [
    {
      "version": 2,
      "previousVersion": 1,
      "type": "ResourceUpdated",
      "modifiedAt": "2020-03-22T23:00:00.000Z",
      "modifiedBy": {
        "isPlatformClient": true,
        "id": "example_user_123",
        "type": "user",
        "customer": {
          "id": "test1",
          "typeId": "customer"
        }
      },
      "resource": {
        "id": "some_entity_id_123",
        "typeId": "product",
        "key": "some_entity_key_123"
      },
      "label": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "previousLabel": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "withoutChanges": false,
      "stores": [
        {
          "key": "store-1",
          "typeId": "store"
        }
      ],
      "businessUnit": {
        "typeId": "business-unit",
        "key": "some_business_unit_key_123"
      },
      "changes": [
        {
          "change": "setKey",
          "previousValue": "Key 1",
          "nextValue": "Key 2",
          "type": "SetKeyChange"
        }
      ]
    }
  ]
}

ModifiedBy

Information about the user or API Client who performed the change. This is a variant of LastModifiedBy.

`id` String	ID of the Merchant Center user who made the change. Present only if `isPlatformClient` is `true`.
`isPlatformClient` Boolean	`true` if the change was made using the Merchant Center.
`type` String	Indicates who performed the change. If the change was made by a user, the value is `"user"`. If the change was made by an API Client with or without an external user ID, the value is `"external-user"`. If the change was made by an Associate, the value is `"associate"`.
`clientId` String	ID of the API Client that made the change. Present only if the change was made using an API Client.
`anonymousId` String	Present only if the change was made using a token from an anonymous session.
`customer` Reference	The Customer who made the change. Present only if the change was made using a token from the password flow.
`associate` Reference	The Associate who made the change in the context of a Business Unit. Only available for B2B-enabled Projects when an Associate acts on behalf of a company using the associate endpoints.

Example: json

{
  "isPlatformClient": true,
  "id": "example_user_123",
  "type": "user",
  "customer": {
    "id": "test1",
    "typeId": "customer"
  }
}

Source

Source of change for the resource.

MerchantCenter: The change was made through the Merchant Center.
ImpEx: The change was made through the now-decommissioned ImpEx tool.
ApiClient: The change was made through an API Client.

ChangeHistoryResourceType

Value of resource types supported in Change History.

associate-role: for AssociateRole - Only available for B2B-enabled Projects.
business-unit: for BusinessUnit - Only available for B2B-enabled Projects.
cart-discount: for CartDiscount
category: for Category
channel: for Channel
customer: for Customer
customer-group: for CustomerGroup
discount-code: for DiscountCode
inventory-entry: for InventoryEntry
key-value-document: for CustomObject
order: for Order
payment: for Payment
product: for Product
product-discount: for ProductDiscount
product-selection: for ProductSelection
product-type: for ProductType
quote-request: for QuoteRequest
quote: for Quote
review: for Review
shopping-list: for ShoppingList
staged-quote: for StagedQuote
state: for State
store: for Store
tax-category: for TaxCategory
type: for Type
zone: for Zone

Label

Provides descriptive information specific to the change.

AssociateRoleLabel B2B

`key` String	User-defined unique identifier of the Associate Role.
`type` String	`"AssociateRoleLabel"`
`name` String	Name of the Associate Role.

BusinessUnitLabel B2B

`key` String	User-defined unique identifier of the Business Unit.
`type` String	`"BusinessUnitLabel"`
`name` String	Name of the Business Unit.

CustomerLabel

`customerNumber` String	User-defined unique identifier of the Customer.
`type` String	`"CustomerLabel"`
`firstName` String	Given name (first name) of the Customer.
`lastName` String	Family name (last name) of the Customer.

CustomObjectLabel

`key` String	User-defined unique identifier of the CustomObject within the defined `container`.
`type` String	`"CustomObjectLabel"`
`container` String	Namespace to group Custom Objects.

LocalizedLabel

`type` String	`"LocalizedLabel"`
`value` LocalizedString	Changed value.

OrderLabel

`type` String	`"OrderLabel"`
`customerEmail` String	Email address of the Customer that the Order belongs to.
`orderNumber` String	User-defined unique identifier of the Order that is unique across a Project.

PaymentLabel

`key` String	User-defined unique identifier of the Payment.
`type` String	`"PaymentLabel"`
`amountPlanned` Money	Money value the Payment intends to receive from the Customer.

ProductLabel

`type` String	`"ProductLabel"`
`slug` LocalizedString	User-defined identifier used in a deep-link URL for the Product.
`name` LocalizedString	Name of the Product.

QuoteRequestLabel

`key` String	User-defined unique identifier of the Quote Request.
`type` String	`"QuoteRequestLabel"`
`customer` Reference	The Buyer who raised the Quote Request.

QuoteLabel

`key` String	User-defined unique identifier of the Quote.
`type` String	`"QuoteLabel"`
`customer` Reference	The Buyer who requested the Quote.
`stagedQuote` Reference	Staged Quote related to the Quote.
`quoteRequest` Reference	Quote Request related to the Quote.

ReviewLabel

`key` String	User-defined unique identifier of the Review.
`type` String	`"ReviewLabel"`
`title` String	Title of the Review.

StagedQuoteLabel

`key` String	User-defined unique identifier of the Staged Quote.
`type` String	`"StagedQuoteLabel"`
`customer` Reference	The Buyer who requested the Quote.
`quoteRequest` Reference	Quote Request related to the Staged Quote.

StringLabel

`type` String	`"StringLabel"`
`value` String	Changed value.

DateStringFilter

This data type consists of one enum value: "now".

PlatformInitiatedChange

Updates that are triggered automatically as a result of a user-initiated change.

excludeAll
changeLineItemName
changeReviewRatingStatistics
setApplicationVersion
setIsValid
setVariantAvailability

Query Records

GET

https://history.{region}.commercetools.com/{projectKey}

The view_audit_log:{projectKey} scope is required, and depending on the resource type queried, their respective scopes must be granted.

OAuth 2.0 Scopes:

view_associate_roles:{projectKey}view_audit_log:{projectKey}view_business_units:{projectKey}view_cart_discounts:{projectKey}view_categories:{projectKey}view_customers:{projectKey}view_customers:{projectKey}:{storeKey}view_customer_groups:{projectKey}view_discount_codes:{projectKey}view_key_value_documents:{projectKey}view_orders:{projectKey}view_orders:{projectKey}:{storeKey}view_payments:{projectKey}view_products:{projectKey}view_product_selections:{projectKey}view_quotes:{projectKey}view_quote_requests:{projectKey}view_shopping_lists:{projectKey}view_shopping_lists:{projectKey}:{storeKey}view_states:{projectKey}view_staged_quotes:{projectKey}view_stores:{projectKey}view_tax_categories:{projectKey}view_types:{projectKey}

Path parameters:

`region` String	The Region in which the project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`expand` Boolean	If `true`, CustomFieldExpandedValue is made available.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`resourceTypes` ChangeHistoryResourceType	Can be used to filter Records of specified resource types. By default, the API returns the Records of all supported resource types. The parameter can be passed multiple times.
`date.from` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. The non-negative integer represents a point in time in the past measured in hours, for example, `24` means 24 hours ago. Can only be used together with the `date.to` query parameter, which has to represent a point in time after the value defined by `date.from`. Default: `24`
`date.to` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. The non-negative integer represents a point in time in the past measured in hours, for example, `24` means 24 hours ago. Can only be used together with the `date.from` query parameter, which has to represent a point in time before the value defined by `date.to`. Default: `now`
`userId` String	ID of the Merchant Center user who made the change. Can be used to query changes made by a Merchant Center user.
`clientId` String	ID of the API Client that made the change.
`customerId` String	ID of the Customer who made the change using a token from the password flow.
`associateId` String	ID of the Associate that made the change. Only Changes to Business Units, Orders, Quote Requests, and Quotes can be filtered.
`businessUnit` String	`key` of the Business Unit linked to the change. Only Changes to Orders, Quote Requests, and Quotes can be filtered. Only available for B2B-enabled Projects.
`type` String	Can be `"ResourceCreated"`, `"ResourceUpdated"`, or `"ResourceDeleted"`. Can be used to filter for a specific type of change (creation, update, or deletion).
`resourceId` String	ID of the changed resource.
`resourceKey` String	Key of the changed resource. Only Changes to Business Units, Associate Roles, Products, and Stores can be filtered.
`source` Source	Source of the change.
`changes` String	Restrict the types of Changes returned by passing the value of the `change` field. The values must belong to the resource type specified in the path parameter. The parameter can be passed multiple times.
`stores` String	`key` of the Store linked to the Change. The parameter can be passed multiple times.
`excludePlatformInitiatedChanges` PlatformInitiatedChange	Excludes Changes initiated by background processes by passing the values of the `change` field. Only Changes of resource type `product`, `product-discount`, `discount-code`, and `shopping-list` can be filtered. Allowed values depend on resource types. To filter Product Changes, `excludeAll`, `changeReviewRatingStatistics`, and `setVariantAvailability` can be passed. To filter Product Discount Changes, `excludeAll` and `setIsValid` can be passed. To filter Discount Code Changes, `excludeAll` and `setApplicationVersion` can be passed. To filter Shopping List Changes, `excludeAll` and `changeLineItemName`can be passed. `excludeAll` excludes all applicable changes. The parameter can be passed multiple times.

Response:

200

RecordPagedQueryResponse

asapplication/json

Request Example:cURL

curl --get https://history.{region}.commercetools.com/{projectKey} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: RecordPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 0,
  "results": [
    {
      "version": 2,
      "previousVersion": 1,
      "type": "ResourceUpdated",
      "modifiedAt": "2020-03-22T23:00:00.000Z",
      "modifiedBy": {
        "isPlatformClient": true,
        "id": "example_user_123",
        "type": "user",
        "customer": {
          "id": "test1",
          "typeId": "customer"
        }
      },
      "resource": {
        "id": "some_entity_id_123",
        "typeId": "product",
        "key": "some_entity_key_123"
      },
      "label": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "previousLabel": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "withoutChanges": false,
      "stores": [
        {
          "key": "store-1",
          "typeId": "store"
        }
      ],
      "businessUnit": {
        "typeId": "business-unit",
        "key": "some_business_unit_key_123"
      },
      "changes": [
        {
          "change": "setKey",
          "previousValue": "Key 1",
          "nextValue": "Key 2",
          "type": "SetKeyChange"
        }
      ]
    }
  ]
}

Query Records for specific resource type

GET

https://history.{region}.commercetools.com/{projectKey}/{resourceType}

The view_audit_log:{projectKey} scope is required, and depending on the resource type queried, their respective scopes must be granted.

OAuth 2.0 Scopes:

view_associate_roles:{projectKey}view_audit_log:{projectKey}view_business_units:{projectKey}view_cart_discounts:{projectKey}view_categories:{projectKey}view_customers:{projectKey}view_customer_groups:{projectKey}view_discount_codes:{projectKey}view_key_value_documents:{projectKey}view_orders:{projectKey}view_orders:{projectKey}:{storeKey}view_payments:{projectKey}view_products:{projectKey}view_product_selections:{projectKey}view_quotes:{projectKey}view_quote_requests:{projectKey}view_shopping_lists:{projectKey}view_states:{projectKey}view_staged_quotes:{projectKey}view_stores:{projectKey}view_tax_categories:{projectKey}view_types:{projectKey}

Path parameters:

`region` String	The Region in which the project is hosted.
`projectKey` String	`key` of the Project.
`resourceType` String	Resource type for which a query is made. The value must be one of the following: `associate-roles`, `business-units`, `cart-discounts`, `categories`, `channels`, `custom-objects`, `customers`, `customer-groups`, `discount-codes`, `inventory`, `orders`, `payments`, `products`, `product-discounts`, `product-selections`, `product-types`, `quote-requests`, `quotes`, `reviews`, `shopping-lists`, `states`, `staged-quotes`, `stores` `tax-categories`, `types`, `zones`

Query parameters:

`expand` Boolean	If `true`, CustomFieldExpandedValue is made available.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`date.from` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. The non-negative integer represents a point in time in the past measured in hours, for example, `24` means 24 hours ago. Can only be used together with the `date.to` query parameter, which has to represent a point in time after the value defined by `date.from`. Default: `24`
`date.to` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. The non-negative integer represents a point in time in the past measured in hours, for example, `24` means 24 hours ago. Can only be used together with the `date.from` query parameter, which has to represent a point in time before the value defined by `date.to`. Default: `now`
`userId` String	ID of the Merchant Center user who made the change. Can be used to query changes made by a Merchant Center user.
`clientId` String	ID of the API Client that made the change.
`customerId` String	ID of the Customer who made the change using a token from the Password Flow.
`associateId` String	ID of the Associate that made the change. Only Changes to Business Units, Orders, Quote Requests, and Quotes can be filtered.
`businessUnit` String	`key` of the Business Unit linked to the change. Only Changes to Orders, Quote Requests, and Quotes can be filtered. Only available for B2B-enabled Projects.
`type` String	Can be `"ResourceCreated"`, `"ResourceUpdated"`, or `"ResourceDeleted"`. Can be used to filter for a specific type of change.
`resourceKey` String	Key of the changed resource. Only Changes to Business Units, Associate Roles, Products, and Stores can be filtered.
`source` Source	Source of the change.
`changes` String	Restrict the types of Changes returned by passing the value of the `change` field. The values must belong to the resource type specified in the path parameter. The parameter can be passed multiple times.
`stores` String	`key` of the Store linked to the Change. The parameter can be passed multiple times.
`excludePlatformInitiatedChanges` PlatformInitiatedChange	Exclude Changes initiated by background processes by passing the values of the `change` field. Only Changes of resource type `product`, `product-discount`, `discount-code`, and `shopping-list` can be filtered. Allowed values depend on resource types. To filter Product Changes, `excludeAll`, `changeReviewRatingStatistics`, and `setVariantAvailability` can be passed. To filter Product Discount Changes, `excludeAll` and `setIsValid` can be passed. To filter Discount Code Changes, `excludeAll` and `setApplicationVersion` can be passed. To filter Shopping List Changes, `excludeAll` and `changeLineItemName`can be passed. `excludeAll` excludes all applicable changes. The parameter can be passed multiple times.

Response:

200

RecordPagedQueryResponse

asapplication/json

Request Example:cURL

curl --get https://history.{region}.commercetools.com/{projectKey}/{resourceType} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: RecordPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 0,
  "results": [
    {
      "version": 2,
      "previousVersion": 1,
      "type": "ResourceUpdated",
      "modifiedAt": "2020-03-22T23:00:00.000Z",
      "modifiedBy": {
        "isPlatformClient": true,
        "id": "example_user_123",
        "type": "user",
        "customer": {
          "id": "test1",
          "typeId": "customer"
        }
      },
      "resource": {
        "id": "some_entity_id_123",
        "typeId": "product",
        "key": "some_entity_key_123"
      },
      "label": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "previousLabel": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "withoutChanges": false,
      "stores": [
        {
          "key": "store-1",
          "typeId": "store"
        }
      ],
      "businessUnit": {
        "typeId": "business-unit",
        "key": "some_business_unit_key_123"
      },
      "changes": [
        {
          "change": "setKey",
          "previousValue": "Key 1",
          "nextValue": "Key 2",
          "type": "SetKeyChange"
        }
      ]
    }
  ]
}

Query Records by resource ID

GET

https://history.{region}.commercetools.com/{projectKey}/{resourceType}/{id}

The view_audit_log:{projectKey} scope is required, and depending on the resource type queried, their respective scopes must be granted.

OAuth 2.0 Scopes:

view_associate_roles:{projectKey}view_audit_log:{projectKey}view_business_units:{projectKey}view_cart_discounts:{projectKey}view_orders:{projectKey}view_orders:{projectKey}:{storeKey}view_categories:{projectKey}view_products:{projectKey}view_customers:{projectKey}view_customer_groups:{projectKey}view_discount_codes:{projectKey}view_key_value_documents:{projectKey}view_payments:{projectKey}view_product_selections:{projectKey}view_quotes:{projectKey}view_quote_requests:{projectKey}view_shopping_lists:{projectKey}view_states:{projectKey}view_staged_quotes:{projectKey}view_stores:{projectKey}view_tax_categories:{projectKey}view_types:{projectKey}

Path parameters:

`region` String	The Region in which the project is hosted.
`projectKey` String	`key` of the Project.
`resourceType` String	Resource type for which a query is made. The value must be one of the following: `associate-roles`, `business-units`, `cart-discounts`, `categories`, `channels`, `custom-objects`, `customers`, `customer-groups`, `discount-codes`, `inventory`, `orders`, `payments`, `products`, `product-discounts`, `product-selections`, `product-types`, `quote-requests`, `quotes`, `reviews`, `shopping-lists`, `states`, `staged-quotes`, `stores` `tax-categories`, `types`, `zones`
`id` String	ID of the resource for which a query is made.

Query parameters:

`expand` Boolean	If `true`, CustomFieldExpandedValue is made available.
`limit` Int	Number of results requested. Default: `20` Minimum: `0` Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0` Maximum: `10000`
`date.from` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. The non-negative integer represents a point in time in the past from now measured in hours, for example, `24` means 24 hours ago. Can only be used together with the `date.to` query parameter, which has to represent a point in time after the value defined by `date.from`. Default: `24`
`date.to` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. The non-negative integer represents a point in time in the past from now measured in hours, for example, `24` means 24 hours ago. Can only be used together with the `date.from` query parameter, which has to represent a point in time before the value defined by `date.to`. Default: `now`
`userId` String	ID of the Merchant Center user who made the change. Can be used to query changes made by a Merchant Center user.
`clientId` String	ID of the API Client that made the change.
`customerId` String	ID of the Customer who made the change using a token from the Password Flow.
`associateId` String	ID of the Associate that made the change. Only Changes to Business Units, Orders, Quote Requests, and Quotes can be filtered.
`businessUnit` String	`key` of the Business Unit linked to the change. Only Changes to Orders, Quote Requests, and Quotes can be filtered. Only available for B2B-enabled Projects.
`type` String	Can be `"ResourceCreated"`, `"ResourceUpdated"`, or `"ResourceDeleted"`. Can be used to filter for a specific type of change.
`source` Source	Source of the change.
`changes` String	Restrict the types of Changes returned by passing the value of the `change` field. The values must belong to the resource type specified in the path parameter. The parameter can be passed multiple times.
`stores` String	`key` of the Store linked to the Change. The parameter can be passed multiple times.
`excludePlatformInitiatedChanges` PlatformInitiatedChange	Exclude Changes initiated by background processes by passing the values of the `change` field. Only Changes of resource type `product`, `product-discount`, `discount-code`, and `shopping-list` can be filtered. Allowed values depend on resource types. To filter Product Changes, `excludeAll`, `changeReviewRatingStatistics`, and `setVariantAvailability` can be passed. To filter Product Discount Changes, `excludeAll` and `setIsValid` can be passed. To filter Discount Code Changes, `excludeAll` and `setApplicationVersion` can be passed. To filter Shopping List Changes, `excludeAll` and `changeLineItemName`can be passed. `excludeAll` excludes all applicable changes. The parameter can be passed multiple times.

Response:

200

RecordPagedQueryResponse

asapplication/json

Request Example:cURL

curl --get https://history.{region}.commercetools.com/{projectKey}/{resourceType}/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

200 Response Example: RecordPagedQueryResponsejson

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 0,
  "results": [
    {
      "version": 2,
      "previousVersion": 1,
      "type": "ResourceUpdated",
      "modifiedAt": "2020-03-22T23:00:00.000Z",
      "modifiedBy": {
        "isPlatformClient": true,
        "id": "example_user_123",
        "type": "user",
        "customer": {
          "id": "test1",
          "typeId": "customer"
        }
      },
      "resource": {
        "id": "some_entity_id_123",
        "typeId": "product",
        "key": "some_entity_key_123"
      },
      "label": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "previousLabel": {
        "value": "some_label",
        "type": "StringLabel"
      },
      "withoutChanges": false,
      "stores": [
        {
          "key": "store-1",
          "typeId": "store"
        }
      ],
      "businessUnit": {
        "typeId": "business-unit",
        "key": "some_business_unit_key_123"
      },
      "changes": [
        {
          "change": "setKey",
          "previousValue": "Key 1",
          "nextValue": "Key 2",
          "type": "SetKeyChange"
        }
      ]
    }
  ]
}

Query Records with GraphQL

Our Change History API is versionless, meaning new types and fields may be introduced at any time without notice. As a result, dynamic schema stitching is discouraged, as it can lead to naming conflicts and unexpected behavior.

GraphQL uses HTTP POST requests to query data. Access to resources is granted by the same scopes that are used on the REST API endpoints.

The view_audit_log:{projectKey} scope is required, and depending on the resource type queried, their respective scopes must be granted too—for example, to filter queries by Categories, provide the view_categories:{projectKey} scope too.

POST

https://history.{region}.commercetools.com/{projectKey}/graphql

Execute a GraphQL request.

OAuth 2.0 Scopes:

view_audit_log:{projectKey}view_categories:{projectKey}

Path parameters:

`region` String	The Region in which the project is hosted.
`projectKey` String	`key` of the Project.

Request Body:GraphQLRequestasapplication/json

Response:

200

GraphQLResponse

asapplication/json

Request Example:cURL

curl https://history.{region}.commercetools.com/{projectKey}/graphql -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "query" : "query getCategoryChanges($startDate: DateFilterValue!, $endDate: DateFilterValue!){categories(date:{from:$startDate to:$endDate}) {results {type modifiedAt changes {previousValue nextValue change} resource{id} }}}",
  "operationName" : "getCategoryChanges",
  "variables" : {
    "startDate" : "2024-09-07T08:53:28.471Z",
    "endDate" : "2024-11-07T08:53:28.471Z"
  }
}
DATA

200 Response Example: GraphQLResponsejson

{
  "data": {
    "categories": {
      "results": [
        {
          "type": "ResourceUpdated",
          "modifiedAt": "2024-11-07T08:53:28.471Z",
          "changes": [
            {
              "previousValue": {
                "en": "Old name for Category"
              },
              "nextValue": {
                "en": "New name for Category"
              },
              "change": "changeName"
            }
          ],
          "resource": {
            "id": "cd260fc9-c575-4ba3-8789-cc4c9980ee4e"
          }
        },
        {
          "type": "ResourceCreated",
          "modifiedAt": "2024-10-22T22:39:44.201Z",
          "changes": [],
          "resource": {
            "id": "ffae2221-40c4-410d-bd13-e0fa4b6a4dd6"
          }
        }
      ]
    }
  }
}

Interactive GraphQL console

You can also use the Apollo GraphQL console to query Records. It lets you explore the documentation for supported GraphQL queries and introspect the GraphQL schema.

In the console, go to Connection settings and enter the values for the following:

For Endpoint, enter:
```
https://history.{region}.commercetools.com/{projectKey}/graphql
```
For Shared headers, select Authorization as the header key and enter Bearer {bearerToken} as the value.

Change History

Hosts.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Representations.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Record.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

RecordPagedQueryResponse.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

ModifiedBy.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Source.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

ChangeHistoryResourceType.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Label.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

AssociateRoleLabel B2B.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

BusinessUnitLabel B2B.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomerLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

CustomObjectLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

LocalizedLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

OrderLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

PaymentLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

ProductLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

QuoteRequestLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

QuoteLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

ReviewLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StagedQuoteLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

StringLabel.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

DateStringFilter.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

PlatformInitiatedChange.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query Records.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query Records for specific resource type.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query Records by resource ID.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Query Records with GraphQL.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Interactive GraphQL console.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}.css-ik49mw{-webkit-flex-shrink:0;-ms-flex-negative:0;flex-shrink:0;}.css-ik49mw *:not([fill='none']){fill:inherit;}.css-ik49mw,.css-ik49mw image{width:24px;height:24px;}

Hosts

Representations

Record

RecordPagedQueryResponse

ModifiedBy

Source

ChangeHistoryResourceType

Label

AssociateRoleLabel B2B

BusinessUnitLabel B2B

CustomerLabel

CustomObjectLabel

LocalizedLabel

OrderLabel

PaymentLabel

ProductLabel

QuoteRequestLabel

QuoteLabel

ReviewLabel

StagedQuoteLabel

StringLabel

DateStringFilter

PlatformInitiatedChange

Query Records

Query Records for specific resource type

Query Records by resource ID

Query Records with GraphQL

Interactive GraphQL console