Audit Log overview

B2CB2BB2XBASIC
Ask about this Page
Copy for LLM
View as Markdown

Overview of the concepts related to Audit Log and the tracking of resource changes in Composable Commerce.

Audit Log tracks and stores changes made to resources in Composable Commerce Projects. B2C Commmerce, B2B Commerce, and B2X Commerce have Audit Log Basic enabled by default, which tracks changes made in the Merchant Center.
The Audit Log Premium Add-On offers a more comprehensive solution suitable for compliance audits and security investigations. It captures changes regardless of the source, including those made via the Merchant Center, and the Import API.
Using the Change History feature, users can query and view changes that happened over time.

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 change type.
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 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 commercetools 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

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.

Data fencing

Data fencing restricts access to Records connected to specific Stores. Audit Log supports Store-based data fencing for Customers, Orders, and Shopping Lists. To view changes, 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 entities

Audit Log tracks changes in the following entity types:

Behavior and record storage

The following behavior applies:

To request a trial of Audit Log Premium, contact the commercetools support team.
The extended tracking offered by Audit Log Premium begins only after the Audit Log Premium Add-On is activated.
To support efficient use of Audit Log, Change History queries are rate-limited. Each Query Records request consumes tokens based on the amount of data queried. The tokens are limited to each Project, and automatically replenish over time.

To assure optimal usage, we reserve the right to adjust the rate limit as necessary.

If the request fails due to the rate limit, a Too Many Requests error is returned. Reduce the date range and resource types in your query to minimize the token usage, or retry the request after some time (indicated in the Retry-After header).

You can track the token usage from the following headers in the response to your request:

  • X-RateLimit-Limit: indicates the total number of tokens available when fully replenished.
  • X-RateLimit-Remaining: indicates the number of tokens available after the current query is completed.
  • X-RateLimit-Request-Cost: indicates the number of tokens used by the current query.

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.