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 example, a user updating their cart is considered a single event.

Event categories and types

There are three categories of events:

• Built-in events
• Custom events
• Advanced events

Choosing the right event

Use case	Event type	Reason
You want to leverage events tied to standard business workflows (cart, checkout, profile updates, etc.).	Built-in events	No setup needed; the event is automatically triggered by the system.
You want to track customer actions with attributes.	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	Legacy approach; advanced events are recommended.

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 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 or advanced events.

Each event is related to a state:

See Customer session states.

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
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
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
talon_session_cancelled	(none)	An open session was cancelled. The state property becomes cancelled. Example: The customer leaves before checkout.	Update customer session
talon_session_revoked	(none)	A closed session was cancelled. The state property becomes cancelled. Example: The customer requests a refund.	Update customer session
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
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
talon_profile_created	Customer Profile Registration	A new customer integration ID is sent to Talon.One.	Update customer profile with runRuleEngine=true
talon_profile_updated	Customer Profile Update	An existing customer profile was modified.	Update customer profile with runRuleEngine=true

Custom events

Custom events are created by you and can be triggered manually. They contain custom attributes.

important

For new integrations, we recommend using advanced events instead of custom events. Alternatively, a built-in event 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.

Advanced events

Advanced events are 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 tutorial.

For more information, see Use events.

Use events

Create an event

Custom events and 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. 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 > Tools > Attributes > Create Attribute.
2. In Entity, select Event.
3. In Event type, enter the name of the new event, for example, pageViewed.
4. In Type, select the type of the new attribute, for example, String.
5. In API name, enter the name of the new attribute.
6. 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 an event, you can trigger it via the Integration API:

• For custom events, use the Track event endpoint.
• For advanced events, use the Track advanced event endpoint.

See API Docs

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 are always triggered implicitly by the system.

Use an event in a rule

When the integration layer registers custom events with the Track event endpoint, you can check specific events in a rule:

1. In a rule, add the Check for event types condition.
2. In Event type, select your event type. For example, pageview.
3. 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.
4. 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 in the Product docs.

Related pages

• Attributes
• Customer session states
• Track event endpoint
• Track advanced event endpoint
• Display events