Audit Log overview

Audit Log tracks and stores changes made to resources in Composable Commerce Projects. Projects have Audit Log Basic enabled by default, which tracks changes made in the Merchant Center.

Change History

Scopes

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}

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 pagination 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 contacting the Composable Commerce support team.

  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

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.

• 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 B2B
• Business Units B2B
• Cart Discounts
• Categories
• Channels
• Custom Objects PREMIUM
• Customers
• Customer Groups
• Discount Codes
• Inventories
• Orders
• Payments PREMIUM
• Products
• Product Discounts
• Product Selections
• Product Types
• Quotes
• Quote Requests
• Reviews PREMIUM
• Shopping Lists PREMIUM
• Staged Quotes
• States PREMIUM
• Stores
• Tax Categories
• Types PREMIUM
• 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, HTTP API, and the Import API for 3 years.