# Audit Log overview Overview of the concepts related to Audit Log and the tracking of resource changes. Audit Log tracks and stores changes made to resources in Projects. [B2C Commmerce](https://docs.commercetools.com/offering/commerce-b2c.md), [B2B Commerce](https://docs.commercetools.com/offering/commerce-b2b.md), and [B2X Commerce](https://docs.commercetools.com/offering/commerce-b2x.md) have Audit Log Basic enabled by default, which tracks changes made in the Merchant Center. The [Audit Log Premium Add-On](https://docs.commercetools.com/offering/audit-log-premium.md) 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](https://docs.commercetools.com/merchant-center/), and the [Import API](https://docs.commercetools.com/api/import-export/overview.md). Using the [Change History](https://docs.commercetools.com/api/history/change-history.md) 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](https://docs.commercetools.com/api/history/overview.md#supported-entities) within a Project. The tracked changes are represented as [Records](https://docs.commercetools.com/api/history/change-history.md#record) containing a list of [Changes](https://docs.commercetools.com/api/history/change-history.md#change) 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](https://docs.commercetools.com/api/general-concepts.md#eventual-consistency), can then be retrieved using the [Change History API](https://docs.commercetools.com/api/history/change-history.md#query-records) or the [Merchant Center](https://docs.commercetools.com/merchant-center/change-history.md). ### 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](https://docs.commercetools.com/api/history/overview.md#data-fencing). ### Hosts The Change History API has different hosts than the HTTP API. For more information, see [Hosts](https://docs.commercetools.com/api/history/change-history.md#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](https://docs.commercetools.com/api/general-concepts.md#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](https://docs.commercetools.com/api/history/change-history.md#query-records-with-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](https://support.commercetools.com/). 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`) ```code 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: ```code GET https://history.{region}.commercetools.com/{project-key}/orders/{id}?date.from=1&date.to=now&limit=20&offset=0&changes=setCustomField ``` ## Stores [Stores](https://docs.commercetools.com/api/projects/stores.md) provide an additional level of granularity to Project data. If a change occurs on a [supported entity type](https://docs.commercetools.com/api/history/overview.md#supported-entities) that is linked to one or more Stores, Audit Log adds the Stores to the [Record](https://docs.commercetools.com/api/history/change-history.md#record). ### Data fencing Data fencing restricts access to [Records](https://docs.commercetools.com/api/history/change-history.md#record) 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](https://docs.commercetools.com/api/scopes.md) are applied to queries: - Customers: if an API Client only has the `view_customers:{projectKey}:store-1` scope, only changes on [Customers](https://docs.commercetools.com/api/projects/customers.md) 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](https://docs.commercetools.com/api/projects/orders.md) 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](https://docs.commercetools.com/api/projects/shoppingLists.md) associated with `store-1` are visible. ## Supported entities Audit Log tracks changes in the following entity types: - [Associate Roles](https://docs.commercetools.com/api/history/change-types/associate-roles.md) - [Business Units](https://docs.commercetools.com/api/history/change-types/business-units.md) - [Cart Discounts](https://docs.commercetools.com/api/history/change-types/cart-discounts.md) - [Categories](https://docs.commercetools.com/api/history/change-types/categories.md) - [Channels](https://docs.commercetools.com/api/history/change-types/channels.md) - [Custom Objects](https://docs.commercetools.com/api/history/change-types/custom-objects.md) - [Customers](https://docs.commercetools.com/api/history/change-types/customers.md) - [Customer Groups](https://docs.commercetools.com/api/history/change-types/customer-groups.md) - [Discount Codes](https://docs.commercetools.com/api/history/change-types/discount-codes.md) - [Inventories](https://docs.commercetools.com/api/history/change-types/inventories.md) - [Orders](https://docs.commercetools.com/api/history/change-types/orders.md) - [Payments](https://docs.commercetools.com/api/history/change-types/payments.md) - [Products](https://docs.commercetools.com/api/history/change-types/products.md) - [Product Discounts](https://docs.commercetools.com/api/history/change-types/product-discounts.md) - [Product Selections](https://docs.commercetools.com/api/history/change-types/product-selections.md) - [Product Types](https://docs.commercetools.com/api/history/change-types/product-types.md) - [Quotes](https://docs.commercetools.com/api/history/change-types/quotes.md) - [Quote Requests](https://docs.commercetools.com/api/history/change-types/quote-requests.md) - [Reviews](https://docs.commercetools.com/api/history/change-types/reviews.md) - [Shipping Methods](https://docs.commercetools.com/api/history/change-types/shipping-methods.md) - [Shopping Lists](https://docs.commercetools.com/api/history/change-types/shopping-lists.md) - [Staged Quotes](https://docs.commercetools.com/api/history/change-types/staged-quotes.md) - [Standalone Prices](https://docs.commercetools.com/api/history/change-types/standalone-prices.md) - [States](https://docs.commercetools.com/api/history/change-types/states.md) - [Stores](https://docs.commercetools.com/api/history/change-types/stores.md) - [Tax Categories](https://docs.commercetools.com/api/history/change-types/tax-categories.md) - [Types](https://docs.commercetools.com/api/history/change-types/types.md) - [Zones](https://docs.commercetools.com/api/history/change-types/zones.md) ## Behavior and record storage The following behavior applies: - Audit Log Basic is included in [B2C Commmerce](https://docs.commercetools.com/offering/commerce-b2c.md), [B2B Commerce](https://docs.commercetools.com/offering/commerce-b2b.md), and [B2X Commerce](https://docs.commercetools.com/offering/commerce-b2x.md). It stores changes originating from the Merchant Center for 1 year. - The [Audit Log Premium Add-On](https://docs.commercetools.com/offering/audit-log-premium.md) stores changes originating from the Merchant Center, [HTTP API](https://docs.commercetools.com/api/), and the [Import API](https://docs.commercetools.com/api/import-export/overview.md) for 3 years. To request a trial of Audit Log Premium, contact the [commercetools support team](https://support.commercetools.com/). 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](https://docs.commercetools.com/api/history/change-history.md#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](https://docs.commercetools.com/api/errors.md#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. ## Related pages - [Section overview page](https://docs.commercetools.com/api.md) - [Next page: Change History API](https://docs.commercetools.com/api/history/change-history.md)