Skip to main content



Hover and click the different entities below to understand how the Talon.One entities are nested and how they interact with each other.


Every request to the Integration API comes from your integrated webshop. Typically, an ecommerce site, a mobile app, or some other source of customer actions.

The target of every request is a given Talon.One Application that contains your campaigns.

You may have multiple Applications within one account, for example staging and production, or different international markets.


Sharing customer activity and campaigns across different Applications in your account is impossible. Consider this when you create several Applications.

Customer profile

A customer profile is Talon.One's internal representation of your customer.

A profile combines data supplied by your Application's attributes with profile data created and updated by campaign rules, loyalty scores, lifetime expenditure etc.

Like any entity, customer profiles can be extended with custom attributes to suit your particular domain. Custom attributes are often used to represent internal counters, such as the number of support tickets a particular customer has opened.

Keep in mind the following information about customer profiles:

As a result, we recommend the following best practices:

  • When using multiple Applications (staging and production), we recommend that you add a per-Application prefix to each customer ID. That way, you can always tell which Application created the profile.
  • Choose an un-mutable ID. For example, an email address doesn't make a good profile ID because a customer might change their registered email.

Customer session

A customer session is a finite container of customer activity within an Application. For example, a customer session can represent a shopping cart, or any transaction leading to a purchase.

A customer session has a unique ID. Your integration owns this ID. Any arbitrary string may be used as long as it can be used to identify the session consistently. Good session ID's are order numbers, or combinations of profile ID and session start time.

A customer session can contain a variety of standard attributes, such as a shipping address or list of shopping cart items. You may also associate attributes to a session, such as a region code derived from a customer billing address.

A customer profile can have multiple customer sessions at one time.

Customer session states

A customer session is in one of the following states and it can move to another state as follows:

customer session states

A session is usually created in the open state (new order) or closed state (legacy order).

  • open: The session can be modified as many times as needed.
  • closed: The session cannot be modified anymore. Also:
    • The session data is fed into the campaign analytics.
    • Potential coupons are redeemed.
  • cancelled: The session had an issue or the closed state is not valid anymore. Also:
    • The session data is removed from the campaign analytics.
    • Expect rollback effects to undo potential previous effects triggered when you closed or opened the session.
  • open: The customer is adding items, referral codes or coupons to their shopping cart.
  • closed: The customer has completed the payment step (or any last step) of the order workflow.
  • cancelled: The customer requested a refund or the payment failed.

Managing the session's state

As an integrator, it is your responsability to set and maintain the state of your sessions. You can do this with the Update customer session endpoint's state property.

When should I update the state?

This depends on your industry, but remember that a closed/cancelled session cannot be updated anymore. For example, if you run an ecommerce website, you typically update the state to closed after the payment step.

Can I create new sessions as closed?

It depends on your business and order workflow, but it is possible and this offers performance benefits as you limit the number of requests.

Typically, if the final session content is known immediately, you can create a closed session at the end of the checkout process. You can also use closed sessions to import historical order data into Talon.One.

Can I leave a session open permanently?

Yes. For example, when a customer creates a cart and never proceeds to checkout. In this case, we recommend you set such sessions to cancelled.

How are sessions handled after an anonymous user has logged in?

  1. When an anonymous user enters the page, create a session using the userID or an empty string as the profile ID.
  2. After the user's logged in, change the profile ID in the current session to the user's customerID.

The session is now connected to this logged-in user.

We recommend calling the Update customer profile for every change in the user profile to keep the user information stored in Talon.One up to date.

When does Talon.One check budget limits

Budget limit checks are done on every session update but the budget counters are incremented when closing a session.

As a result, a customer may add a coupon to their cart that might not be usable anymore by the time they checkout because other sessions closed in the meantime.

When are loyalty points updated and coupons redeemed?

Loyalty points are updated when the session is closed or cancelled. Coupons, referral codes and awarded giveaway items are redeemed when the session is closed.

All other effects, such as attribute updates and coupon/referral creations are triggered instantly on session updates unless you use a session state = closed in your rules.

See also:


An event is a single occurrence of a specific customer action. Every event is linked to a customer session.

Talon.One provides generic events but you can also define custom events for activities specific to your business.

For more information, see


A giveaway allows you to offer an external reward to a customer. For example, your giveaway strategy could be to offer an Amazon gift card to customers that buy a specific item. Only admin users can create giveaways. The rewards defined in them can be accessed in any Application and campaign in your account via rule effects. These rewards are generally codes.

Keep in mind that giveaways are different than discounts, they do not modify the customer's order.

To learn how to create giveaways, see creating giveaways.


Campaigns are the main entity marketers interact with in Talon.One. Each campaign is defined by at least one rule.


Rules rely on aggregated data and data from the current request and can trigger effects. A rule has one of more conditions, and triggers one or more effects.

For example, a rule might have a condition of customer has completed an order of over $100 AND the previous order happened more than 90 days ago. An effect can, for example, update profile/session data, set discounts, return customer-facing messages, or send requests to pre-defined external APIs.


A campaign also contains a pool of coupons. Coupons can have arbitrary attributes associated to them. For example, the ID of a particular customer for a personalized coupon code, or a region code for coupons that are only valid in certain areas. These constraints are enforced by the rule, not the coupon.


Coupon are redeemed after the session they are part of is closed. Redeeming a coupon code increments the usage counter by 1.


Referrals are a separate entity in Talon.One. Like coupons, they act like tickets but they are bound to 2 people:

  • The advocate: the person who invited their friend via the referral program. They own the referral code.
  • The friend: the person who receives the invite from an advocate. They use the referral code.

For more information, see Referral program


Referral codes are redeemed after the redeem referral code effect is triggered by a rule. Redeeming a referral code increments the usage counter by 1.

While campaigns, rules, and coupons are most commonly created manually in the Campaign Manager Application, you can also create and manage them programmatically via the Management API.

See also: