19th Nov 2020



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



Every request to the Integration API comes from one or more applications. An application could be an e-commerce site, a mobile app, or some other source of customer actions, and is the owner of the API key used to send integration data.

You may have multiple applications within one account, e.g. for staging & production, or different international markets. When deciding on how to divide your data among multiple applications, the main consideration is sharing of customer activity & campaigns. It's not possible to share customer activity and campaigns across different applications in your account.

Customer Profile

A Customer Profile is Talon.One's internal representation of your customer. A profile combines data supplied by your applications — attributes such as names, e-mail addresses, home addresses, phone numbers, etc — with profile data created & updated by campaign rules — loyalty scores, lifetime expenditure and so on.

The unique ID for a customer profile is completely controlled by your application. It may be any arbitrary string, but should be something that you can use to reliably refer to a logged in user. For example, email addresses do not make good profile ID's if your customers can change their registered email. A further consideration when using multiple applications is whether a given customer is "the same" in different applications. In general we strongly recommend giving profile ID's a per-application prefix to avoid confusion and conflicting updates from different applications.

In addition to standard built-in attributes, customer profiles can be extended with attributes to suit your particular domain. A common use case would be internal scores or counters, such as the number of support tickets a particular customer has opened. More details can be found in our best practices guide to attributes.

See also:

Customer Session

A Customer Session is a finite container of customer activity within an application. Most commonly, a customer session corresponds to a single order or billing cycle, and will have multiple updates before being finalized. Once a session is finalized no further updates are allowed, except to cancel a previously closed session (e.g. if a payment failed).

Much like customer profiles, the unique identifier of a customer session is completely controlled by your integration. Any arbitrary string may be used, but it should be something that remains stable until the activity is finished. Examples of 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 with a session, such as a region code derived from a customer billing address.

See also:


Each customer session contains one or more events: single occurrences of various customer actions. For example, updating a customer session directly records a talon_session_updated event. These built-in events are recorded implicitly whenever new data is received via the Integration API.

Talon.One also allows you to define completely custom events for activities specific to your business. For example, you might wish to provide an incentive to customers who have viewed a specific product. You could then define a viewed_product event that can be sent by your backend, and add conditions in your campaigns so that only customers who had viewed certain products qualify.

See also:

Campaigns: Rules, Coupons and Referrals

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

Rules may use both aggregated data and data from the current request to make their decisions. For example, a rule might have a condition of customer is Canadian AND has completed an order with a total value over $100 AND last order was more than 90 days ago. The effects that may be taken when a rule matches include updating profile/session data, setting discounts, returning customer-facting messages, or sending requests to pre-defined external APIs.

A campaign also contains a pool of coupons. Coupons may also have arbitrary attributes associated with them, such as the ID of a particular customer for a personalized coupon code, or a region code for coupons that are only valid in certain areas. It's important to understand that the enforcement of these constraints is the responsibility of the ruleset and not the coupon.

ℹ️ Coupon redemption: Coupon will be redeemed after the session they are part of gets closed. Redeeming a coupon code will increase the usage-counter by 1.

Besides vouchers, referrals are a separate entity in Talon.One. Similar to coupon they act like ticket with the difference that they are bound to 2 persons:

  • the advocate: the person who invited their friend via the referral program ("owner/creator" of the referral code)
  • the friend: the person who receives the invite from an advocate (the one using the referral code)

Additonal information about referral code can be found here: Referral Program

ℹ️ Referral redemption: Referral codes will be redeemed after the "redeem referral code" effect has been triggered by a rule. Redeeming a referral code will increase the usage counter by 1.

While campaigns, rulesets, and coupons are most commonly created manually in our Campaign Manager application, it is also possible to create and manage them programmatically via the Management API. See the Management API reference for more details.

See also:

Still need help? Get in touch!
Last updated on 19th Nov 2020

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