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 and Import and Export, 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/`

The Change History API is available only in Google Cloud and AWS Regions.

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

by Project Key

by Resource Type

by ID

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.
`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`. 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.
`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 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"
}