# Event stores

Event stores are associated with all the other resources and generated upon every creation, update, or cancellation of the related resource to help you track the history of each resource's data changes by providing [paginated event access](#fetching-the-event-stores-of-a-resource) via API.

{% hint style="info" %}
The [versions](https://docs.commercelayer.io/core-api-reference/versions) API endpoint will be deprecated soon and dismissed shortly after. Start using event stores to get the same information you got from versions, and more. If you're an enterprise customer, you can also connect to our [event stream hub](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/event-stream-hub) and consume updates as they happen (no polling required).
{% endhint %}

Each event store object contains information about the event that generated it (one of `create` or `update`), the type of resource that was created or updated, the request involved, the application, worker, or user that triggered the change, and more. You can find the change history inside the `payload` object, which shows, for each modified attribute, the values before and after the change.

{% hint style="info" %}
You can [retrieve](https://docs.commercelayer.io/core-api-reference/event_stores/retrieve) a single event store by ID. No other direct CRUD operation is permitted on the event stores resource. You can fetch the [paginated](#pagination) list of event stores associated with a specific resource [as a relationship](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/fetching-relationships) the resource itself.
{% endhint %}

## Fetching the event stores of a resource

To fetch all the events involving a specific resource, send a `GET` request to the `/api/{{resource_name}}/:id/event_stores` endpoint, where `{{resource_name}}` is the name of the resource (e.g. `skus`, `customers`, `orders`, etc.). You need to use [integration](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#integration) API credentials.

### Example

{% tabs %}
{% tab title="Request" %}
The following request fetches the event stores associated with the SKU identified by the ID `xYZkjABcde`:

```shell
curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/event_stores' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning a paginated collection of event store objects:

```json
{
  "data": [
    {
      "id": "1234567891234-0",
      "type": "event_stores",
      "links": {
        "self": null
      },
      "attributes": {
        "resource_type": "skus",
        "resource_id": "xYZkjABcde",
        "event": "update",
        "payload": {
            "updated_at": {
            "from": "2024-07-04T08:20:33.514Z",
            "to": "2025-08-01T13:31:34.796Z"
            }
        },
        "who": {
          "application": {
            "id": "kJWxyCDefg",
            "client_id": "app-CL13ntID_KOwFhtKMvQIvj-KZY",
            "kind": "skus",
            "public": false
          },
          "owner": {
            "id": "ZTShiJOpqr",
            "type": "User",
            "email": "john@example.com",
            "first_name": "John",
            "last_name": "Doe"
          }
        },
        "created_at": "2025-08-01T13:31:34.000+00:00",
        "updated_at": "2025-08-01T13:31:34.000+00:00",
        "reference": {},
        "reference_origin": {},
        "metadata": {}
      },
      "meta": {
        "mode": "test",
        "trace_id": "1234a5bf723d29d58c5cdc18e06ae45f126e7212eb427905ba1e2f994f3c882e"
      }
    },
    {
      "id": "13456789123456-0",
      "type": "event_stores",
      "links": {
        "self": null
      },
      "attributes": {
        "resource_type": "skus",
        "resource_id": "xYZkjABcde",
        "event": "update",
        "payload": {
          "updated_at": {
            "from": "2025-08-01T13:31:34.796Z",
            "to": "2025-08-01T13:32:11.395Z"
          },
          "metadata": {
            "from": {},
            "to": {
              "year": "2021"
            }
          }
        },
        "who": {
          "application": {
            "id": "kJWxyCDefg",
            "client_id": "app-CL13ntID_KOwFhtKMvQIvj-KZY",
            "kind": "skus",
            "public": false
          },
          "owner": {
            "id": "ZTShiJOpqr",
            "type": "User",
            "email": "john@example.com",
            "first_name": "John",
            "last_name": "Doe"
          }
        },
        "created_at": "2025-08-01T13:32:11.000+00:00",
        "updated_at": "2025-08-01T13:32:11.000+00:00",
        "reference": {},
        "reference_origin": {},
        "metadata": {}
      },
      "meta": {
        "mode": "test",
        "trace_id": "3456k7bf723d29d58c5cdc18e06ae45f126e7212eb427905ba1e2f994f3c882e"
      }
    },
    {
      "other": "... 8 event stores (first page)"
    }   
  ],
  "meta": {},
  "links": {
    "next": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/event_stores?page[after]=1a123456-a95b-4212-88c9-3478697a2ad8&page[size]=10"
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The returned event stores list is neither filterable nor sortable by any attribute.
{% endhint %}

### Pagination

When you fetch the event stores of a resource, you get paginated results.

{% hint style="warning" %}
The pagination method used for the event store resource is slightly different from [the one used for all the other resources](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/pagination), being based on a cursor instead of the page number.
{% endhint %}

No record or page count is available in the `meta` attribute. Unless you're requesting the last page, you can find the URL of the next page in the `links` attribute:

```json
{
  "data": [...],
  "meta": {},
  "links": {
    "next": "https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/event_stores?page[after]=1a123456-a95b-4212-88c9-3478697a2ad8&page[size]=10"
  }
}
```

{% hint style="info" %}
If no query parameter is specified, pagination starts from the first page, and the default page size is **10**. The maximum page size allowed is **25**, but we recommend using a lower value unless strictly necessary.
{% endhint %}

If you need to modify the default page size, use the `page[size]` query parameter in your request. To navigate through the paginated results, use the `page[after]` query parameters in your request:

```shell
curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde/event_stores?page[after]=1a123456-a95b-4212-88c9-3478697a2ad8&page[size]=5' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
```