Documentation

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.

On this page, you can find the common types used by the Change History API. To view change types related to entities, see their dedicated pages.

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:
RegionAPI 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
RecordPagedQueryResponse
ModifiedBy
Source
ChangeHistoryResourceType
Label-AssociateRoleLabel -BusinessUnitLabel -CustomerLabel-CustomObjectLabel-LocalizedLabel-OrderLabel-PaymentLabel-ProductLabel-QuoteRequestLabel-QuoteLabel-ReviewLabel-ShippingMethodLabel-StandalonePriceLabel-StagedQuoteLabel-StringLabel
DateStringFilter
PlatformInitiatedChange
Change-UnknownChange
ChangeValue-AssetChangeValue-CustomFieldExpandedValue-CustomShippingMethodChangeValue-DeliveryChangeValue-ParcelChangeValue-ShippingMethodChangeValue-TransactionChangeValue-ChangeValueChangeValue-ChangeValueAbsoluteChangeValue-ChangeValueRelativeChangeValue-ChangeValueGiftLineItemChangeValue-ChangeValueExternalChangeValue
ChangeTargetChangeValue-ChangeTargetLineItemsChangeValue-ChangeTargetCustomLineItemsChangeValue-ChangeTargetShippingChangeValue-ChangeTargetMultiBuyLineItemsChangeValue-ChangeTargetMultiBuyCustomLineItemsChangeValue-ChangeTargetPatternChangeValue
Embedded values-AttributeValue-EnumValue-LocalizedEnumValue-FieldDefinitionOrderValue-InventoryQuantityValue-ShoppingListLineItemValue-SetCartClassificationShippingRateInputValue-SetCartScoreShippingRateInputValue-ShippingMethodTaxAmountChangeValue-TaxedPrice-TextLineItemValue-ValidFromAndUntilValue

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 change type. 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
shipping-method
for ShippingMethod
shopping-list
for ShoppingList
staged-quote
for StagedQuote
standalone-price
for StandalonePrice
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.

ShippingMethodLabel

key​
String​

User-defined unique identifier of the Shipping Method.

type​
String​
"ShippingMethodLabel"
name​
String​

Unique name identifier of the Shipping Method.

StandalonePriceLabel

key​
String​

User-defined unique identifier of the Standalone Price.

type​
String​
"StandalonePriceLabel"
sku​
String​

Unique Product SKU variant identifier to which the Standalone Price is associated.

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
addInheritedAssociate
changeIncludedInStatistics
changeInheritedAssociate
changeLastVariantId
changeLineItemName
changeLineItemPublished
changeReviewRatingStatistics
changeTopLevelUnit
removeInheritedAssociate
setAncestors
setApplicationVersion
setInheritedAssociates
setInheritedStores
setIsValid
setLineItemDeactivatedAt
setProductCount
setReservations
setVariantAvailability

Change

Difference between the previous and next version of a resource represented by previousValue (omitted, for example, on creations) and nextValue of the associated change. A Change can also contain extra fields that provide further information.

They are not identical to the actual update actions sent.

type​
String​

Unique discriminator value to reliably deserialize the data type.

change​
String​
Change type on a resource that is similar to the update action it relates to, where possible. It is not a unique identifier for the data structure, for example, the setDescription change can occur with a localized and non-localized representation.
Records can be filtered by this value using the changes query parameter.

UnknownChange

Change triggered when the format of changes on an entity is not identified by Audit Log.

type​
String​
"UnknownChange"
change​
String​

Identifier for the type of modification.

previousValue​
Any​

Value before the change.

nextValue​
Any​

Value after the change.

ChangeValue

AssetChangeValue

id​
String​
id of the Asset.
name​
LocalizedString​

Name of the Asset.

CustomFieldExpandedValue

Only present if expand is set to true.
name​
String​

Name of the Custom Field.

value​
Any​
CustomFieldValue based on the FieldType.
label​
LocalizedString​

User-defined label of the Custom Field.

CustomShippingMethodChangeValue

name​
String​

Name of the Custom ShippingMethod.

DeliveryChangeValue

items​
Array of DeliveryItem​
Line Items or Custom Line Items shipped in the Delivery.
address​
Address​

Address to which the parcels are delivered.

parcels​
Array of Parcel​
Parcels included in the Delivery.

ParcelChangeValue

id​
String​
id of the Parcel.
createdAt​
String​

Date and time (UTC) the Parcel was created.

ShippingMethodChangeValue

id​
String​
id of the ShippingMethod.
name​
String​

Name of the ShippingMethod.

TransactionChangeValue

id​
String​
id of the Transaction.
interactionId​
String​

Identifier used by the interface that manages the Transaction (usually the PSP).

timestamp​
String​

Date and time (UTC) the Transaction took place.

ChangeValueChangeValue

Indicates how a Cart or Product is discounted:

ChangeValueAbsoluteChangeValue

type​
String​
"absolute"
money​
Array of Money​

Money values in different currencies.

ChangeValueRelativeChangeValue

type​
String​
"relative"
permyriad​
Int​

Fraction (per ten thousand) the price is reduced by. For example, 1000 results in a 10% price reduction.

ChangeValueGiftLineItemChangeValue

type​
String​
"giftLineItem"
product​
Reference​
Reference to a Product.
variantId​
Int​
id of the ProductVariant.
supplyChannel​
Reference​
Channel with ChannelRoleEnum InventorySupply.
distributionChannel​
Reference​
Channel with ChannelRoleEnum ProductDistribution.

ChangeValueExternalChangeValue

type​
String​
"external"

ChangeTargetChangeValue

Indicates the segment of the Cart that is discounted:

ChangeTargetLineItemsChangeValue

type​
String​
"lineItems"
predicate​
String​
Valid LineItem target predicate.

ChangeTargetCustomLineItemsChangeValue

type​
String​
"customLineItems"
predicate​
String​
Valid CustomLineItem target predicate.

ChangeTargetShippingChangeValue

type​
String​
"shipping"

ChangeTargetMultiBuyLineItemsChangeValue

type​
String​
"multiBuyLineItems"
predicate​
String​
Valid LineItem target predicate.
triggerQuantity​
Int​

Quantity of Line Items that triggered the application of the discount.

discountedQuantity​
Int​

Quantity of Line Items discounted per application of this discount.

maxOccurrence​
Int​

Maximum number of times the discount is applicable.

selectionMode​
SelectionMode​

SelectionMode based on which particular Line Items were discounted.

ChangeTargetMultiBuyCustomLineItemsChangeValue

type​
String​
"multiBuyCustomLineItems"
predicate​
String​
Valid CustomLineItem target predicate.
triggerQuantity​
Int​

Quantity of Custom Line Items that triggered the application of the discount.

discountedQuantity​
Int​

Quantity of Custom Line Items discounted per application of this discount.

maxOccurrence​
Int​

Maximum number of times the discount is applicable.

selectionMode​
SelectionMode​

SelectionMode based on which particular Custom Line Items were discounted.

ChangeTargetPatternChangeValue

type​
String​
"pattern"
triggerPattern​
Array of PatternComponent​

Defines the set of units of (Custom) Line Items in a Cart that triggered the discount application.

targetPattern​
Array of PatternComponent​

Defines the set of units of (Custom) Line Items in a Cart on which the Discount is applied.

maxOccurrence​
Int​

Maximum number of times the Discount applies on a Cart.

If empty, the Discount applies indefinitely.

selectionMode​
SelectionMode​

Indicates which of the matching units of (Custom) Line Items were discounted.

Embedded values

AttributeValue

name​
String​

Name of the Attribute set.

value​
Any​
Value set for the Attribute determined by the AttributeType:

EnumValue

key​
String​

Key of the value used as a programmatic identifier.

label​
String​

Descriptive label of the value.

LocalizedEnumValue

key​
String​

Key of the value used as a programmatic identifier.

label​
LocalizedString​

Descriptive localized label of the value.

FieldDefinitionOrderValue

name​
String​
Name of the FieldDefinition.
label​
LocalizedString​

Descriptive label of the field.

InventoryQuantityValue

quantityOnStock​
Int​
Overall amount of stock (availableQuantity + reserved).
availableQuantity​
Int​
Available amount of stock (quantityOnStock - reserved).

ShoppingListLineItemValue

id​
String​
id of the ShoppingListLineItem.
name​
LocalizedString​

Name of the corresponding Product the Product Variant belongs to.

variantId​
Int​
id of the ProductVariant the ShoppingListLineItem refers to.

SetCartClassificationShippingRateInputValue

key​
String​

Key of the value used as a programmatic identifier.

type​
String​
"Classification"
label​
LocalizedString​

Descriptive localized label of the value.

SetCartScoreShippingRateInputValue

type​
String​
"Score"
score​
Int​

Abstract value for categorizing a Cart.

ShippingMethodTaxAmountChangeValue

taxedPrice​
TaxedPrice​
Taxed price for the Shipping Method based on taxRate.
taxRate​
TaxRate​

Tax rate set externally for the Shipping Method.

TaxedPrice

totalNet​
CentPrecisionMoney​

Total net price of the Cart or Order.

totalGross​
CentPrecisionMoney​

Total gross price of the Cart or Order.

taxPortions​
Array of TaxPortion​

Taxable portions added to the total net price.

Calculated from the TaxRates.
totalTax​
CentPrecisionMoney​

Total tax applicable for the Cart or Order.

Automatically calculated as the difference between the totalGross and totalNet values.

TextLineItemValue

id​
String​
id of the TextLineItem.
name​
LocalizedString​

Name of the TextLineItem.

ValidFromAndUntilValue

validFrom​
String​

Date and time (UTC) from when the Discount is effective.

validUntil​
String​

Date and time (UTC) until when the Discount is effective.

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.
If the request exceeds the rate limit, a TooManyRequests error is returned.
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_shipping_methods:{projectKey}view_shopping_lists:{projectKey}view_shopping_lists:{projectKey}:{storeKey}view_staged_quotes:{projectKey}view_standalone_prices:{projectKey}view_states:{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 change type (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 changeLineItemNamecan be passed.
excludeAll excludes all applicable changes.
The parameter can be passed multiple times.
Response:
200

RecordPagedQueryResponse

as
application/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.
If the request exceeds the rate limit, a TooManyRequests error is returned.
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_shipping_methods:{projectKey}view_shopping_lists:{projectKey}view_staged_quotes:{projectKey}view_standalone_prices:{projectKey}view_states:{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, payment-methods, 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 change type.
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 changeLineItemNamecan be passed.
excludeAll excludes all applicable changes.
The parameter can be passed multiple times.
Response:
200

RecordPagedQueryResponse

as
application/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.
If the request exceeds the rate limit, a TooManyRequests error is returned.
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_shipping_methods:{projectKey}view_shopping_lists:{projectKey}view_staged_quotes:{projectKey}view_standalone_prices:{projectKey}view_states:{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, payment-methods, 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 change type.
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 changeLineItemNamecan be passed.
excludeAll excludes all applicable changes.
The parameter can be passed multiple times.
Response:
200

RecordPagedQueryResponse

as
application/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

as
application/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.