Event stores

The event store object and how to fetch 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 via API.

The 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 and consume updates as they happen (no polling required).

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.

You can retrieve a single event store by ID. No other direct CRUD operation is permitted on the event stores resource. You can fetch the paginated list of event stores associated with a specific resource as a relationship the resource itself.

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 API credentials.

Example

Request

The following request fetches the event stores associated with the SKU identified by the ID xYZkjABcde:

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'

Response

On success, the API responds with a 200 OK status code, returning a paginated collection of event store objects:

{
  "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": "[email protected]",
            "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": "[email protected]",
            "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"
  }
}

The returned event stores list is neither filterable nor sortable by any attribute.

Pagination

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

The pagination method used for the event store resource is slightly different from the one used for all the other resources, being based on a cursor instead of the page number.

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:

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

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.

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:

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'