---
title: "Custom events"
slug: "custom-events"
abstract: "Understand custom events, which can capture any action you choose to track."
---
# Custom events

A custom event can capture any action you choose to track. For example, clicks on components and how many times a site visitor adds items to their wish list.

You can send custom events by using the [`event`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-events/cloud-sdk-events-browser/functions/cloud-sdk-events-browser-event.html "event") function and passing it the [custom event data object](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-reference/cloud-sdk-events/cloud-sdk-events-browser/interfaces/cloud-sdk-events-eventdata.html "EventData").

> [!note]
> The `event` function can also send a standard event, such as `IDENTITY`, `ORDER_CHECKOUT` or `SC_SEARCH` events if the correct payload is provided.
>
> In general, we recommend that you send standard events using their dedicated functions instead of the `event` function. For example, send an `IDENTITY` event using the [`identity`](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events/cloud-sdk-events-browser-identity.html "identity") function.

## The custom event data object

The custom event data object represents all the required and optional data about the event.

This is the object where [you provide data about the event](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events.html#UUID-b78ff86e-4442-71e7-edc6-81adf8fabe27_section-idm46246153457504340509825241 "The data in the events"). All this data is sent to Sitecore, so make sure to provide the correct data depending on your organization's requirements. Construct the object in the following way:

- Provide the name of the custom event. We recommend you choose a unique event name by including some unique value, such as the [name of your site](https://doc.sitecore.com/sai/en/developers/jss/217/jss-sai/walkthrough--connecting-the-next-js-application-directly-to-the-experience-edge-endpoint.html). For example, `"myretailsite:CLICKED_PROMO"`.

    > [!important]
    > To send a custom event, do not set the name of a custom event to a [reserved event name](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events/cloud-sdk-events-eventdata.html#UUID-51b04d7e-6f8d-f0bc-4c3c-cf225761d0e5_para-idm1903440876470242) such as `"VIEW"` or `"IDENTITY"`, or a name starting with `SC_`.
    >
    > The only scenario where can use reserved event names in the custom event data object is when you use the `event` function to send a standard event, such as `IDENTITY`, `ORDER_CHECKOUT`, or `SC_SEARCH`.

- Optionally, you can:
    - Provide data such as the channel and the language of the page where the event triggered, and you can also add any custom attributes of your choice.
    - Include the [extension data object](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events.html#UUID-b78ff86e-4442-71e7-edc6-81adf8fabe27_section-idm234411833561624 "Data provided by you").

## Examples

> [!tip]
> During development, use your web browser's developer tools to [check the payload](https://doc.sitecore.com/sdk/en/developers/005/cloud-sdk/cloud-sdk-concepts/concepts-tracking/events.html#UUID-b78ff86e-4442-71e7-edc6-81adf8fabe27_section-idm234451877631545 "Checking the payload") containing all the event data that is sent to Sitecore.

Example 15. Sending a custom event

Here's an example custom event data object for a custom event named `"myretailsite:CLICKED_PROMO"`. The object contains all the required event data, and some optional event data and extension data. You can send this event by passing the object to the `event` function:

::::tabs
:::tab{title="Browser module"}

```typescript
const eventData: any = {
  type: "myretailsite:CLICKED_PROMO",
  language: "EN",
  page: "home",
  channel: "WEB",
  currency: "EUR",
  extensionData: { customKey: "customValue" }
};

event(eventData);
```

:::
:::tab{title="Server module"}

```typescript
const eventData: any = {
  type: "myretailsite:CLICKED_PROMO",
  language: "EN",
  page: "home",
  channel: "WEB",
  currency: "EUR",
  extensionData: { customKey: "customValue" }
};

await event(request, eventData);
```

:::
::::

For this custom event data object, the following payload is sent to Sitecore:

```json
{
  "browser_id": "a38b230c-11eb-4cf9-8d5d-274e9f344925​",
  "channel": "WEB",
  "client_key": "",
  "currency": "EUR",
  "ext": {
    "customKey": "customValue"
  },
  "language": "EN",
  "page": "home",
  "pos": "",
  "requested_at": "2026-10-05T10:`36:32`.506Z",
  "type": "myretailsite:CLICKED_PROMO"
}
```