This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Change History

Change History tracks creations, deletions, and updates of resources on Composable Commerce.

Change History provides a historical view into changes made to resources in your Project. Changes made to resources are stored along with the time of change, the source of the change, and, if provided, the user who made the change. These changes, which are eventually consistent, can then be retrieved using the Change History API or Merchant Center.

The Audit Log tracks and stores resource changes made after 15 March 2021. The tracked changes are represented as Records containing a list of Changes that happened together. Changes have varying data representations depending on the type of change.

A maximum of 100 000 Records can be stored for up to 1 year. These limits can be extended, subject to a separate fee, by contacting Support via the Support Portal.

The API response data is based on the changes tracked and stored by Audit Log. The default Audit Log setting is to only track Merchant Center-originated changes, and therefore any response data targeted at a source other than the Merchant Center is an empty set.

Hosts

The Change History API has different hosts from the HTTP API. The Change History API 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/`
China (AWS, Ningxia)	`https://history.cn-northwest-1.aws.commercetools.cn/`

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) when 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.
`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.
`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.
`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 the change was made in 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. Present only if the Associate acts on behalf of a company using the associate endpoints.
`isPlatformClient` Boolean	`true` if the change was made using the Merchant Center or ImpEx.

Example: json

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

ChangeHistoryResourceType

Represents the supported resource types. The value must be one of the following:

associate-role for AssociateRole
business-unit for BusinessUnit
cart-discount for CartDiscount
category for Category
channel for Channel
customerfor 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
state for State
staged-quote for StagedQuote
store for Store
tax-category for TaxCategory
type for Type
zone for Zone

Label

Provides descriptive information specific to the change.

AssociateRoleLabel

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

BusinessUnitLabel

`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_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.

Query parameters:

`expand` Boolean	If `true`, CustomFieldExpandedValue is made available.
`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`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`. Defaults to `24`. 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`.
`date.to` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. Defaults to `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`.
`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.
`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` String	Source from which changes were made: `"MerchantCenter"`, `"ImpEx"`, or `"ApiClient"`.
`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:

200RecordPagedQueryResponseasapplication/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:

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.
`offset` Int	Number of elements skipped.
`date.from` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. Defaults to `24`. 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`.
`date.to` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. Defaults to `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`.
`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.
`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` String	Name of the source with which changes were made. Can be `"MerchantCenter"`, `"ImpEx"`, or `"ApiClient"`.
`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:

200RecordPagedQueryResponseasapplication/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.
`offset` Int	Number of elements skipped.
`date.from` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. Defaults to `24`. 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`.
`date.to` Can be Float, DateTime, or DateStringFilter	Can be DateTime, non-negative integer, or `now`. Defaults to `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`.
`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.
`type` String	Can be `"ResourceCreated"`, `"ResourceUpdated"`, or `"ResourceDeleted"`. Can be used to filter for a specific type of change.
`source` String	Name of the source with which changes were made. Can be `"MerchantCenter"`, `"ImpEx"`, or `"ApiClient"`.
`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:

200RecordPagedQueryResponseasapplication/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

You can access the GraphQL endpoint with the following URL:

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

The endpoint accepts HTTP POST requests with the following fields in the JSON body:

query - String
GraphQL query as a string.
variables - Object - Optional
JSON object that defines variables for your query.
operationName - String - Optional
Name of the operation, if you have defined several of them in the query.

An example of a query for changes on Products to be executed as cURL command is shown below:

$ curl -X POST https://history.{region}.commercetools.com/{projectKey}/graphql \
  -H "Content-Type:application/json" \
  -H "Authorization:Bearer ..." \
  -d '{"query": "query (resourceTypes: Product) {results {type changes {previousValue nextValue change} }}" }'

Interactive GraphQL console

You can also use an interactive GraphiQL environment to query Records. The console lets you explore the docs for the supported GraphQL queries and introspect the GraphQL schema.

It is available on the following URL:

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

To use it, you must provide a valid OAuth token for an API Client with the above-mentioned scopes.

{
  "authorization": "Bearer XXXXXXX"
}

Stores data fencing

Stores provide an extra level of granularity to Project data.

If Audit Log tracked a Change on a supported resource with stores linked to it, then the Audit log Record has attached the store or stores that were linked at the time the Change was initiated.

A Record attached to a Store means that users would have limited access to the change depending on the Store they are assigned to. The access will vary depending on the entity type.

Audit Log considers the two following premises:

A Record without Stores is considered a global change.
A Record with a Store attached to it is considered a Store-specific change.

See below how Store-specific scopes are applied on queries for Changes on supported resource types:

Customers: If an API Client only has the view_customers:{projectKey}:store-1 scope, only changes on Customers associated with store-1 and global changes are visible.
Orders: If an API Client only has the view_orders:{projectKey}:store-1 scope, only changes on Orders associated with store-1 are visible.
Shopping Lists: If an API Client only has the view_shopping_lists:{projectKey}:store-1 scope, only changes on Shopping Lists associated with store-1 are visible.