Skip to main content

Entities

Overview#

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

Application#

Every request to the Integration API comes from an Application. An Application is typically an ecommerce 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

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.

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. For example, a customer session can represent a shopping cart, or any transaction leading to a purchase.

A customer session has a state that corresponds to a single order or billing cycle, and goes through multiple updates before it is finalized.

Once a session is finalized no further updates are allowed, apart from the cancellation of a closed session, for example when a payment failed.

Like customer profiles, 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.

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

Customer session states#

A customer session is in a given state at a time. It usually is created in the open or closed state. It can evolve to another state as follows:

customer session states
  • open: The session can be modified as many times as needed.
  • closed: The session cannot be modified anymore.
  • cancelled: The session had an issue or the closed state is not valid anymore.
Example
  • open: The customer is adding items to a shopping cart.
  • closed: The customer has completed the payment step of the order workflow.
  • cancelled: The customer requested a refund, or the payment failed.

Managing the session 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 keep in mind 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 in one instant, 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.

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:

Events#

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

Giveaways#

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#

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

Rules#

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.

Coupons#

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#

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: