Audit Log overview

Change History

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

The tracked changes are represented as Records containing a list of Changes that occurred together. Changes have varying data representations depending on the type of change.

Changes 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 the Merchant Center.

Scopes

To access the Change History API, you must create an API Client that includes the view_audit_log:{projectKey} scope. In addition, you must assign view or manage scopes for the entity types that you want to view in Change History.

For example, to create an API Client that has access to changes on Category and Customer entity types, you would assign the following scopes:

• view_audit_log:{projectKey}
• view_categories:{projectKey} or manage_categories:{projectKey}
• view_customers:{projectKey} or manage_customers:{projectKey}

API Clients with Store-specific scopes can view changes associated with a Store. The entity type determines whether only changes associated with a specific Store are shown, or if global changes are shown in addition. For more information, see Stores data fencing.

Hosts

The Change History API has different hosts than the HTTP API. For more information, see Hosts.

Best practices

When using the Change History API, we recommend that you do the following:

• Filter requests, when possible:

  • Use the shortest date range needed.
  • Provide the resource type, source of change, and/or change type.
  • Provide a specific unique identifier.

• Use paging and offsets for large result sets (for example, 20 results per response).

• Avoid making API calls in response to an event stream or message subscription.

• Cache results when using longer date ranges (spanning multiple months) that are routinely queried.

• Consider using GraphQL when:

  • Integrating Audit Log within a frontend application, especially if the application is built using React.
  • Querying specific fields and you don't need the entire payload that REST provides.

• Avoid repetitive API calls in business logic processes. If necessary, implement a cache.

  Change History is not meant to handle constant event-driven requests in online transaction processing workloads. If you have a use case where you need specific data that can only be found in Change History, we recommend that you open a ticket via the Support Portal.

  Projects that query the Change History API repetitively without notifying commercetools of the use case may face restrictions.

Example queries

The following example query includes many of the best practice recommendations:

• Uses a short date range
• Limits results to 20
• Uses an offset
• Provides a resource type (Order)
• Provides a change type (setCustomField)

GET https://history.{region}.commercetools.com/{project-key}?date.from=24&date.to=now&limit=20&offset=0&resourceTypes=order&changes=setCustomField

To query a unique resource ID within a date range and by change type:

GET https://history.{region}.commercetools.com/{project-key}/orders/{id}?date.from=1&date.to=now&limit=20&offset=0&changes=setCustomField

Stores data fencing

Stores provide an additional level of granularity to Project data.

If a change occurs on a supported entity type that is linked to one or more Stores, Audit Log adds the Stores to the Record.

To view the change in Change History, API Clients must be granted Store-specific permissions. In addition, the entity type determines whether only changes associated with a specific Store are shown or if global changes are shown as well.

The following two principles apply:

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

The following examples show how Store-specific scopes are applied to queries:

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

Supported entity types

Audit Log tracks changes in the following entity types:

• Associate Roles
• Business Units
• Cart Discounts
• Categories
• Channels
• Custom Objects
• Customers
• Customer Groups
• Discount Codes
• Inventories
• Orders
• Payments
• Products
• Product Discounts
• Product Selections
• Product Types
• Quotes
• Quote Requests
• Reviews
• Shopping Lists
• Staged Quotes
• States
• Stores
• Tax Categories
• Types
• Zones

Behavior and record storage

Audit Log tracks and stores resource changes made after 15 March 2021. It does not track or store read requests made to resources within a Project.

The following behavior applies:

• Audit Log Basic stores changes originating from the Merchant Center for 1 year.
• Audit Log Premium stores changes originating from the Merchant Center, APIs, and the Import feature for 3 years.

To request a trial of Audit Log Premium, please contact Support via the Support Portal.