# Event entity

> Events are a type of entity. An event represents a single occurrence of a specific customer action related to a customer session or a customer profile.

> For the complete documentation index, see [llms.txt](https://docs.talon.one/llms.txt).

For example, a user updating their cart is considered a single event.

## Event categories and types

There are three **categories** of events:

- [Built-in events](/docs/dev/concepts/entities/events.md#built-in-events)
- [Custom events](/docs/dev/concepts/entities/events.md#custom-events)
- [Advanced events](/docs/dev/concepts/entities/events.md#advanced-events)

<details>
  <summary>**Choosing the right event**</summary>
  | Use case                                                                                                 | Event type                          | Reason                                                                                     |
  | -------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
  | You want to leverage events tied to standard business workflows (cart, checkout, profile updates, etc.). | [Built-in events](#built-in-events) | No setup needed; the event is automatically triggered by the system.                       |
  | You want to track customer actions with attributes.                                                      | [Advanced events](#advanced-events) | Recommended for new integrations. Includes idempotency and session linking. Safe to retry. |
  | You're maintaining legacy integrations and can't use advanced events yet.                                | [Custom events](#custom-events)     | Legacy approach; advanced events are recommended.                                          |
</details>

All events also have a **type**, which is effectively the name of the event. For built-in
events, the type is predefined by Talon.One, for example, `talon_session_created`. For
custom and advanced events, you can create your own type and name it, for example,
`pageViewed`.

### Built-in events

Built-in events are provided by Talon.One and are tied to a customer session or a customer
profile. They are triggered depending on the endpoints used by your integration, and by
the content of the requests.

**Example**: When your integration layer calls the [Update customer
session](/integration-api/#tag/Customer-Sessions/operation/updateCustomerSession)
endpoint, for instance when a customer adds an item to their cart, an implicit
`talon_session_updated` event happens.

Built-in events are always triggered implicitly by the system. To trigger events
explicitly, use [custom events](#custom-events) or [advanced events](#advanced-events).

Each event is related to a state:

<StatesWithEvents alt="States and events" className="figma" />

See [Customer session states](/docs/dev/concepts/entities/customer-sessions).

| Event type                         | Name in Rule Builder          | Trigger criterion                                                                                                                                                                               | API Endpoint                                                                                                                  |
| ---------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `talon_session_created`            | Customer Session Creation     | A new session integration ID is sent to Talon.One so a new session is created. The `state` property becomes `open`.**Example:** The customer creates a cart.                          | [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)                           |
| `talon_session_updated`            | Customer Session Update       | An open session was updated. The `state` property remains `open`.**Example:** The customer adds an item to the cart.                                                                  | [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)                           |
| `talon_session_closed`             | Customer Session Closing      | An open session was closed. The `state` property becomes `closed`.**Example:** The customer completes the payment step.                                                               | [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)                           |
| `talon_session_cancelled`          | (none)                        | An open session was cancelled. The `state` property becomes `cancelled`.**Example:** The customer leaves before checkout.                                                             | [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)                           |
| `talon_session_revoked`            | (none)                        | A closed session was cancelled. The `state` property becomes `cancelled`.**Example:** The customer requests a refund.                                                                 | [Update customer session](/integration-api#tag/Customer-sessions/operation/updateCustomerSessionV2)                           |
| `talon_session_partially_returned` | (none)                        | A closed session had some items returned. The `state` property becomes `partially_returned`.**Example:** The customer returns some of the items and expects the corresponding refund. | [Return cart items](/integration-api#tag/Customer-sessions/operation/returnCartItems)                                         |
| `talon_session_reopened`           | (none)                        | A closed session was reopened. The `state` property becomes `open`.**Example:** The closed order has to be modified after payment was processed.                                      | [Reopen customer session](/integration-api#tag/Customer-sessions/operation/reopenCustomerSession)                             |
| `talon_profile_created`            | Customer Profile Registration | A new customer integration ID is sent to Talon.One.                                                                                                                                             | [Update customer profile](/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2) with `runRuleEngine=true` |
| `talon_profile_updated`            | Customer Profile Update       | An existing customer profile was modified.                                                                                                                                                      | [Update customer profile](/integration-api#tag/Customer-profiles/operation/updateCustomerProfileV2) with `runRuleEngine=true` |

### Custom events

Custom events are [created](#create-an-event) by you and can be triggered manually. They
contain [custom attributes](/docs/dev/concepts/attributes.md#custom-attributes).

:::important
For new integrations, we recommend using [advanced events](#advanced-events) instead of
custom events. Alternatively, a [built-in event](#built-in-events)
may fit your business scenario.
:::

**Example**: You create a custom event that triggers when a user visits a page. This event
contains a custom `url` attribute. You can then use this attribute in the Rule Engine and
Integration API.

For more information, see [Use events](#use-events).

### Advanced events

Advanced events are [custom events](#custom-events) with two additional capabilities:

- **Idempotency**: Each advanced event has a unique identifier. If you send the same event
  more than once, Talon.One rejects the duplicate with a `409` error instead of processing
  it again. This makes it safe to retry without the risk of awarding points or triggering
  effects twice.
- **Connected session**: You can attach a `connectedSessionId` to reference a previously
  closed session. The Rule Engine can then read data from that session, such as the
  session total, to inform rule evaluation. This is useful when an action happens after
  the session closes, for example when a shipment is delivered.

For a use case, see our [Award loyalty points after
delivery](/docs/dev/tutorials/award-loyalty-points-after-delivery.md) tutorial.

For more information, see [Use events](#use-events).

## Use events

### Create an event

[Custom events](#custom-events) and [advanced events](#advanced-events) must be created in
Talon.One before you can trigger them. Both event categories are created in the same way,
and both contain one or more [attributes](/docs/dev/concepts/attributes.md). Even if you
do not need an attribute in your use case, the event you create must contain one.

To create an event, create a custom attribute with the **Event** entity:

1. Click <Account className="icon"/> > <Tools className="icon"/> **Tools** >
   **Attributes** > **Create Attribute**.
1. In **Entity**, select **Event**.
1. In **Event type**, enter the name of the new event, for example, `pageViewed`.
1. In **Type**, select the type of the new attribute, for example, **String**.
1. In **API name**, enter the name of the new attribute.
1. Fill the other fields as needed and click **Create Attribute**.

**Example**: To create a `pageViewed` event that contains a `url` attribute, set the
**Event type** to `pageViewed` and the **API name** to `url`.

The event now automatically contains a first attribute of the name and type you just
chose. You can now trigger the event or add more attributes to this event.

To add more attributes, repeat the procedure, but ensure you always use the same value for
**Event type**.

### Trigger an event

After you have [created](#create-an-event) an event, you can trigger it via the
Integration API:

- For [custom events](#custom-events), use the [Track event](/integration-api#tag/Events/operation/trackEventV2)
  endpoint.
- For [advanced events](#advanced-events), use the [Track advanced event](/integration-api#tag/Events/operation/trackEventV3)
  endpoint.

<Button variant="primary" size="l" href="/integration-api#tag/Events">
  See API Docs
</Button>

The response contains the effects generated by the Rule Engine and the processed event.
Use the `responseContent` property to request additional entities, such as the customer
profile, loyalty data, or triggered campaigns.

[Built-in events](#built-in-events) are always triggered implicitly by the system.

### Use an event in a rule

When the integration layer registers custom events with the [Track
event](/integration-api#tag/Events/operation/trackEventV2) endpoint, you can
check specific events in a rule:

1. In a rule, add the **Check for event types** condition.
1. In **Event type**, select your event type. For example, `pageview`.
1. In the next field, select one of the attributes of your event type. Click **And...** to
   check extra attributes of your event, if you have any.
1. Finish your rule by setting an effect and save.

Whenever the selected event type is triggered, the rule is evaluated.

## Display triggered events

See [Display events](/docs/product/applications/display-events.md) in the Product docs.

## Related pages

- [Attributes](/docs/dev/concepts/attributes.md)
- [Customer session states](/docs/dev/concepts/entities/customer-sessions.md#customer-session-states)
- [Track event](/integration-api/#tag/Events/operation/trackEventV2) endpoint
- [Track advanced event](/integration-api#tag/Events/operation/trackEventV3) endpoint
- [Display events](/docs/product/applications/display-events.md#list-events)