24th Feb 2021



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 one or more applications. An application is typically an e-commerce site, a mobile app, or some other source of customer actions. An application is the owner of the API key used to send integration data.

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

Important: It's not possible to share customer activity and campaigns across different applications in your account. 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.

Every customer profile has an unique identifier. Your application owns this ID. For example, an email address doesn't make a good profile ID because a customer might change their registered email.

When using multiple applications, consider whether you should use the same ID for a given customer across all the applications. In general, we recommend that you add a per-application prefix to each customer ID. This helps avoid confusion and conflicting updates from different applications.

In addition to built-in attributes, 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.

For more information, see:

Customer session

A customer session is a finite container of customer activity within an application. It is updated several times until it reaches its final state, the closed state. Once a session is closed, it cannot be updated but it can be canceled, for example when a payment failed.

Manage the life cycle of a session via the updateCustomerSession endpoint, by setting the state property.

Like a customer profile, a customer session has a unique ID. You 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.

See also:


An event is a single occurrence of various customer actions.

Each customer session contains one or more events. For example, updating a customer session records a talon_session_updated event. Such built-in events are recorded implicitly whenever new data is received via the Integration API.

You can also define custom events for activities specific to your business. For example, if you want to provide an incentive to customers who have viewed a specific product:

  1. Define a viewed_product event sent by your backend on specific criteria.
  2. Add a Check event condition in your campaigns to use your custom event.

See also:

Campaigns, rules, coupons and referrals

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.

Note: 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

Note: 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:

Still need help? Get in touch!
Last updated on 24th Feb 2021

Was this article helpful?

Thank you! You have already voted

If you’d like a member of our support team to respond to you, please send a note to support@talon.one