Skip to main content

Entities

Overview​

The available entities are described in the diagram below. Use this diagram to you identify how entities are nested.

For example:

  • You can have many Applications in your deployment.
  • Rules are specific to a given campaign.
  • A loyalty program can be shared across all the Applications of your deployment.

Application​

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.

note

You cannot share campaigns across different Applications, but you can copy campaigns to a different Application.

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 from the same environment (for example, live), 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 or partially returned states are not valid anymore. Also:
    • The session data is removed from the campaign analytics.
    • Coupons redeemed in the session are usable again.
    • Coupons created in the session are not deleted.
    • The impact of the session's effects on campaign budgets is reverted, except for coupon creations.
    • Rollback effects undo previous effects triggered when you closed or opened the session.
    • Attribute value updates are not rolled back.
  • partially returned: One or more cart items have been returned and the closed state is not valid anymore. Also:
    • Rollback effects undo previous effects triggered when you closed or opened the session.
    • The impact of the session's effects on campaign budgets is reverted.
    • Attribute value updates are not rolled back.
Examples
  • 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 full refund or the payment failed.
  • partially returned: The customer returned some of the items and expects the corresponding refund.

Each state is related to a built-in event.

Managing the session's state​

As an integrator, it is your responsibility to set and maintain the state of your sessions. You can do this with the following endpoints:

When should I update the state?

This depends on your industry and order workflow. The most important transition is when you set a session's state to closed because it updates the budgets of the campaign and applies all the effects.

For example, if you run an ecommerce website, in general, the session should be closed when your customer confirms the order but before you submit a capture request to your payment service provider. If the payment fails, you can either:

Can I create new sessions as closed?

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

There are 2 usual use cases:

  • If the final session content is known immediately, you can create a closed session on order confirmation.
  • Importing historical order data into Talon.One. See Importing customer sessions.
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 signed in?

This is typically a 2-step process:

  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 has signed in, change the profile ID in the current session to the user's customerID.

The session is now connected to this signed-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 impact of the session's effects on the campaign budgets is effective when closing the 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 condition 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 can consist in offering 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 giveaway programs.

Campaigns​

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

Rules​

There are the following types of rules:

  • Promotion rules
  • Strikethrough rules

Promotion rules rely on aggregated data and data from the current request, and they are evaluated when using the Integration API endpoints. A promotion rule has one or more conditions and triggers one or more effects.

For example, a promotion rule might have a condition of a 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.

Strikethrough rules work together with cart item catalogs and apply effects on specific cart items. They are not evaluated in the customer session and are only triggered when changes occur in the campaign or in the cart item catalog connected to the corresponding Application.

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

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

Referrals​

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

  • 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 when the session is closed. Redeeming a referral code increments the redemption 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.