12th May 2020

API Reference

The Integration API is how you push data into the Talon.One environment. You can create profiles for your customers, sessions to group their activity, and custom events to track specific actions that do not fit into the session data model.

You will need Authentication to make requests to the API.

#

Update a Customer Profile

PUT  /v1/customer_profiles/{integrationId}

Update (or create) a Customer Profile. This profile information can then be matched and/or updated by campaign Rules.

The integrationId may be any identifier that will remain stable for the customer. For example, you might use a database ID, an email, or a phone number as the integrationId. It is vital that this ID not change over time, so don't use any identifier that the customer can update themselves. E.g. if your application allows a customer to update their e-mail address, you should instead use a database ID.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

#Example

#Request Schema

URL Parameter

integrationId string required

The custom identifier for this profile, must be unique within the account.

Query Parameter

dry boolean

Flag to indicate whether to skip persisting the changes or not (Will not persist if set to 'true').

Body Parameter

attributes object

Arbitrary properties associated with this item

#Response Schema

sessionobject

Customer Session

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon string

Any coupon code entered.

referral string

Any referral code entered.

state string
default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems array

Serialized JSON representation.

name string
minlength: 1

Serialized JSON representation.

sku string
minlength: 1

Serialized JSON representation.

quantity integer
format: 1

Serialized JSON representation.

price number

Serialized JSON representation.

category string

Serialized JSON representation.

weight number

Weight of item in mm

height number

Height of item in mm

width number

Width of item in mm

length number

Length of item in mm

position number

Position of the Cart Item in the Cart (calculated internally)

attributes object

Arbitrary properties associated with this item

adjustment array

Serialized JSON representation.

identifiers array

Identifiers for the customer, this can be used for limits on values such as device ID.

identifiers string

Identifiers for the customer, this can be used for limits on values such as device ID.

total number

The total sum of the cart in one session.

attributes object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession boolean

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

discounts object

A map of labelled discount values, values will be in the same currency as the application associated with the session.

profileobject

Customer Profile

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

attributes object

Arbitrary properties associated with this item

accountId integer

The ID of the Talon.One account that owns this profile.

closedSessions integer

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales number

Sum of all purchases made by this customer

loyaltyMemberships array

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivity string
format: date-time

Timestamp of the most recent event received from this customer

eventobject

Event

id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

type string
minlength: 1

A string representing the event. Must not be a reserved event name.

attributes object

Arbitrary additional JSON data associated with the event.

sessionId string

The ID of the session that this event occurred in.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries array

Ledger entries for the event.

meta object

Event

campaigns object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason object

Event

referralRejectionReason object

Event

warnings object

Event

loyaltyobject

Loyalty program information

programs object

A map holding information about the loyalty programs balance

coupon
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

The ID of the campaign that owns this entity.

value string
minlength: 4

The actual coupon code.

usageLimit integer

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimit number

The amount of discounts that can be given with this coupon code.

startDate string
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDate string
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounter integer

The number of times this coupon has been successfully used.

discountCounter number

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemainder number

The remaining discount this coupon can give.

attributes object

Arbitrary properties associated with this item

referralId integer

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationId string

The Integration ID of the customer that is allowed to redeem this coupon.

importId integer

The ID of the Import which created this coupon.

reservation boolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchId string

The id of the batch the coupon belongs to.

#

Update a Customer Session

PUT  /v1/customer_sessions/{customerSessionId}

Update (or create) a Customer Session. For example, the items in a customers cart are part of a session.

The Talon.One platform supports multiple simultaneous sessions for the same profile, so if you have multiple ways of accessing the same application you have the option of either tracking multiple independent sessions or using the same session across all of them. You should share sessions when application access points share other state, such as the users cart. If two points of access to the application have independent state (e.g. a user can have different items in their cart across the two) they should use independent customer session ID's.

The profileId parameter in the request body should correspond to an integrationId for a customer profile, to track an anonymous session use the empty string ("") as the profileId. Note that you do not need to create a customer profile first: if the specified profile does not yet exist, an empty profile will be created automatically.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

The currency for the session and the cart items in the session is the same as that of the application with which the session is associated.

#Example

#Request Schema

URL Parameter

customerSessionId string required

The custom identifier for this session, must be unique within the account.

Query Parameter

dry boolean

Flag to indicate whether to skip persisting the changes or not (Will not persist if set to 'true').

Body Parameter

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon string

Any coupon code entered.

referral string

Any referral code entered.

state string
default: open open,closed,cancelled

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems array

Serialized JSON representation.

name string
minlength: 1

Serialized JSON representation.

sku string
minlength: 1

Serialized JSON representation.

quantity integer
format: 1

Serialized JSON representation.

price number

Serialized JSON representation.

category string

Serialized JSON representation.

weight number

Weight of item in mm

height number

Height of item in mm

width number

Width of item in mm

length number

Length of item in mm

position number

Position of the Cart Item in the Cart (calculated internally)

attributes object

Arbitrary properties associated with this item

adjustment array

Serialized JSON representation.

payFromLoyaltyProgram integer

Loyalty Program to be used for payment

pointPayment integer
format: 1

Amount of points to be spend

remainingPrice number

Remaining price in currency after payment in points has been made

identifiers array

Identifiers for the customer, this can be used for limits on values such as device ID.

identifiers string

Identifiers for the customer, this can be used for limits on values such as device ID.

total number

The total sum of the cart in one session.

attributes object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

#Response Schema

sessionobject

Customer Session

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon string

Any coupon code entered.

referral string

Any referral code entered.

state string
default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems array

Serialized JSON representation.

name string
minlength: 1

Serialized JSON representation.

sku string
minlength: 1

Serialized JSON representation.

quantity integer
format: 1

Serialized JSON representation.

price number

Serialized JSON representation.

category string

Serialized JSON representation.

weight number

Weight of item in mm

height number

Height of item in mm

width number

Width of item in mm

length number

Length of item in mm

position number

Position of the Cart Item in the Cart (calculated internally)

attributes object

Arbitrary properties associated with this item

adjustment array

Serialized JSON representation.

identifiers array

Identifiers for the customer, this can be used for limits on values such as device ID.

identifiers string

Identifiers for the customer, this can be used for limits on values such as device ID.

total number

The total sum of the cart in one session.

attributes object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession boolean

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

discounts object

A map of labelled discount values, values will be in the same currency as the application associated with the session.

profileobject

Customer Profile

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

attributes object

Arbitrary properties associated with this item

accountId integer

The ID of the Talon.One account that owns this profile.

closedSessions integer

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales number

Sum of all purchases made by this customer

loyaltyMemberships array

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivity string
format: date-time

Timestamp of the most recent event received from this customer

eventobject

Event

id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

type string
minlength: 1

A string representing the event. Must not be a reserved event name.

attributes object

Arbitrary additional JSON data associated with the event.

sessionId string

The ID of the session that this event occurred in.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries array

Ledger entries for the event.

meta object

Event

campaigns object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason object

Event

referralRejectionReason object

Event

warnings object

Event

loyaltyobject

Loyalty program information

programs object

A map holding information about the loyalty programs balance

coupon
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

The ID of the campaign that owns this entity.

value string
minlength: 4

The actual coupon code.

usageLimit integer

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimit number

The amount of discounts that can be given with this coupon code.

startDate string
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDate string
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounter integer

The number of times this coupon has been successfully used.

discountCounter number

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemainder number

The remaining discount this coupon can give.

attributes object

Arbitrary properties associated with this item

referralId integer

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationId string

The Integration ID of the customer that is allowed to redeem this coupon.

importId integer

The ID of the Import which created this coupon.

reservation boolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchId string

The id of the batch the coupon belongs to.

#

Track an Event

POST  /v1/events

Records an arbitrary event in a customer session. For example, an integration might record an event when a user updates their payment information.

The sessionId body parameter is required, an event is always part of a session. Much like updating a customer session, if either the profile or the session do not exist, a new empty one will be created. Note that if the specified session already exists, it must belong to the same profileId or an error will be returned.

As with customer sessions, you can use an empty string for profileId to indicate that this is an anonymous session.

Updating a customer profile will return a response with the full integration state. This includes the current state of the customer profile, the customer session, the event that was recorded, and an array of effects that took place.

#Example

#Request Schema

Query Parameter

dry boolean

Flag to indicate whether to skip persisting the changes or not (Will not persist if set to 'true').

Body Parameter

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

type string required
minlength: 1

A string representing the event. Must not be a reserved event name.

attributes object required

Arbitrary additional JSON data associated with the event.

sessionId string required
minlength: 1

The ID of the session that this event occurred in.

#Response Schema

sessionobject

Customer Session

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

coupon string

Any coupon code entered.

referral string

Any referral code entered.

state string
default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems array

Serialized JSON representation.

name string
minlength: 1

Serialized JSON representation.

sku string
minlength: 1

Serialized JSON representation.

quantity integer
format: 1

Serialized JSON representation.

price number

Serialized JSON representation.

category string

Serialized JSON representation.

weight number

Weight of item in mm

height number

Height of item in mm

width number

Width of item in mm

length number

Length of item in mm

position number

Position of the Cart Item in the Cart (calculated internally)

attributes object

Arbitrary properties associated with this item

adjustment array

Serialized JSON representation.

identifiers array

Identifiers for the customer, this can be used for limits on values such as device ID.

identifiers string

Identifiers for the customer, this can be used for limits on values such as device ID.

total number

The total sum of the cart in one session.

attributes object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession boolean

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

discounts object

A map of labelled discount values, values will be in the same currency as the application associated with the session.

profileobject

Customer Profile

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

attributes object

Arbitrary properties associated with this item

accountId integer

The ID of the Talon.One account that owns this profile.

closedSessions integer

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales number

Sum of all purchases made by this customer

loyaltyMemberships array

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivity string
format: date-time

Timestamp of the most recent event received from this customer

eventobject

Event

id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

type string
minlength: 1

A string representing the event. Must not be a reserved event name.

attributes object

Arbitrary additional JSON data associated with the event.

sessionId string

The ID of the session that this event occurred in.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries array

Ledger entries for the event.

meta object

Event

campaigns object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason object

Event

referralRejectionReason object

Event

warnings object

Event

loyaltyobject

Loyalty program information

programs object

A map holding information about the loyalty programs balance

coupon
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

The ID of the campaign that owns this entity.

value string
minlength: 4

The actual coupon code.

usageLimit integer

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimit number

The amount of discounts that can be given with this coupon code.

startDate string
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDate string
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounter integer

The number of times this coupon has been successfully used.

discountCounter number

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemainder number

The remaining discount this coupon can give.

attributes object

Arbitrary properties associated with this item

referralId integer

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationId string

The Integration ID of the customer that is allowed to redeem this coupon.

importId integer

The ID of the Import which created this coupon.

reservation boolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchId string

The id of the batch the coupon belongs to.

#

Create a referral code for an advocate

POST  /v1/referrals

Creates a referral code for an advocate. The code will be valid for the referral campaign for which is created, indicated in the campaignId parameter, and will be associated with the profile specified in the advocateProfileIntegrationId parameter as the advocate's profile.

#Example

#Request Schema

Body Parameter

campaignId integer required

ID of the campaign from which the referral received the referral code.

advocateProfileIntegrationId string required

The Integration Id of the Advocate's Profile

friendProfileIntegrationId string

An optional Integration ID of the Friend's Profile

startDate string
format: date-time

Timestamp at which point the referral code becomes valid.

expiryDate string
format: date-time

Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

#Response Schema

idinteger

Unique ID for this entity.

createdstring
format: date-time

The exact moment this entity was created.

campaignIdinteger

ID of the campaign from which the referral received the referral code.

advocateProfileIntegrationIdstring

The Integration Id of the Advocate's Profile

friendProfileIntegrationIdstring

An optional Integration ID of the Friend's Profile

startDatestring
format: date-time

Timestamp at which point the referral code becomes valid.

expiryDatestring
format: date-time

Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

codestring
minlength: 4

The actual referral code.

usageCounterinteger

The number of times this referral code has been successfully used.

usageLimitinteger

The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.

#

Delete the personal data of a customer.

DELETE  /v1/customer_data/{integrationId}

Delete all attributes on the customer profile and on entities that reference that customer profile.

#Example

#Request Schema

URL Parameter

integrationId string required

The custom identifier for this profile, must be unique within the account.

#Response Schema

#

Create a new coupon reservation

POST  /v1/coupon_reservations/{couponValue}

Creates a coupon reservation for all passed customer profiles on this couponID

#Example

#Request Schema

URL Parameter

couponValue string required

The value of a coupon

Body Parameter

integrationIDs array required

List of Integration IDs

integrationIDs string

List of Integration IDs

#Response Schema

idinteger

Unique ID for this entity.

createdstring
format: date-time

The exact moment this entity was created.

campaignIdinteger

The ID of the campaign that owns this entity.

valuestring
minlength: 4

The actual coupon code.

usageLimitinteger

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimitnumber

The amount of discounts that can be given with this coupon code.

startDatestring
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDatestring
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounterinteger

The number of times this coupon has been successfully used.

discountCounternumber

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemaindernumber

The remaining discount this coupon can give.

attributesobject

Arbitrary properties associated with this item

referralIdinteger

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationIdstring

The Integration ID of the customer that is allowed to redeem this coupon.

importIdinteger

The ID of the Import which created this coupon.

reservationboolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchIdstring

The id of the batch the coupon belongs to.

#

Delete coupon reservations

DELETE  /v1/coupon_reservations/{couponValue}

Removes all passed customer profiles reservation from this coupon

#Example

#Request Schema

URL Parameter

couponValue string required

The value of a coupon

Body Parameter

integrationIDs array required

List of Integration IDs

integrationIDs string

List of Integration IDs

#Response Schema

#

Get the users that have this coupon reserved

GET  /v1/coupon_reservations/customerprofiles/{couponValue}

Returns all users that have this coupon marked as reserved

#Example

#Request Schema

URL Parameter

couponValue string required

The value of a coupon

#Response Schema

integrationIdstring
format: string

The ID used for this entity in the application system.

createdstring
format: date-time

The exact moment this entity was created.

attributesobject

Arbitrary properties associated with this item

accountIdinteger

The ID of the Talon.One account that owns this profile.

closedSessionsinteger

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSalesnumber

Sum of all purchases made by this customer

loyaltyMembershipsarray

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer
format: date-time

The ID of the loyalty program belonging to this entity.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivitystring
format: date-time

Timestamp of the most recent event received from this customer

#

Get an inventory of all data associated with a specific customer profile.

GET  /v1/customer_profiles/{integrationId}/inventory

Get information regarding entities referencing this customer profile's integrationId. Currently we support customer profile information, referral codes and reserved coupons. In the future, this will be expanded with loyalty points.

#Example

#Request Schema

URL Parameter

integrationId string required

The custom identifier for this profile, must be unique within the account.

Query Parameter

profile boolean

optional flag to decide if you would like customer profile information in the response

referrals boolean

optional flag to decide if you would like referral information in the response

coupons boolean

optional flag to decide if you would like coupon information in the response

#Response Schema

profileobject

Customer Profile

integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

attributes object

Arbitrary properties associated with this item

accountId integer

The ID of the Talon.One account that owns this profile.

closedSessions integer

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales number

Sum of all purchases made by this customer

loyaltyMemberships array

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivity string
format: date-time

Timestamp of the most recent event received from this customer

referralsarray
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

ID of the campaign from which the referral received the referral code.

advocateProfileIntegrationId string

The Integration Id of the Advocate's Profile

friendProfileIntegrationId string

An optional Integration ID of the Friend's Profile

startDate string
format: date-time

Timestamp at which point the referral code becomes valid.

expiryDate string
format: date-time

Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

code string
minlength: 4

The actual referral code.

usageCounter integer

The number of times this referral code has been successfully used.

usageLimit integer

The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.

couponsarray
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

The ID of the campaign that owns this entity.

value string
minlength: 4

The actual coupon code.

usageLimit integer

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimit number

The amount of discounts that can be given with this coupon code.

startDate string
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDate string
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounter integer

The number of times this coupon has been successfully used.

discountCounter number

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemainder number

The remaining discount this coupon can give.

attributes object

Arbitrary properties associated with this item

referralId integer

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationId string

The Integration ID of the customer that is allowed to redeem this coupon.

importId integer

The ID of the Import which created this coupon.

reservation boolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchId string

The id of the batch the coupon belongs to.

#

Update a Customer Session V2

PUT  /v2/customer_sessions/{customerSessionId}

Update (or create) a Customer Session. For example, the items in a customers cart are part of a session.

The Talon.One platform supports multiple simultaneous sessions for the same profile, so if you have multiple ways of accessing the same application you have the option of either tracking multiple independent sessions or using the same session across all of them. You should share sessions when application access points share other state, such as the users cart. If two points of access to the application have independent state (e.g. a user can have different items in their cart across the two) they should use independent customer session ID's.

The profileId parameter in the request body should correspond to an integrationId for a customer profile, to track an anonymous session use the empty string ("") as the profileId. Note that you do not need to create a customer profile first: if the specified profile does not yet exist, an empty profile will be created automatically.

Updating a customer profile will return a response with the requested integration state. This includes the effects that were generated due to triggered campaigns, the created coupons and referral objects, as well as any entity that was requested in the request parameter "responseContent".

The currency for the session and the cart items in the session is the same as that of the application with which the session is associated.

#Example

#Request Schema

URL Parameter

customerSessionId string required

The custom identifier for this session, must be unique within the account.

Query Parameter

dry boolean

Flag to indicate whether to skip persisting the changes or not (Will not persist if set to 'true').

Body Parameter

customerSession required

The customer session update details

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

couponCodes array

Any coupon codes entered.

couponCodes string

Any coupon codes entered.

referralCode string

Any referral code entered.

state string
default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems array

All items the customer will be purchasing in this session

name string
minlength: 1

All items the customer will be purchasing in this session

sku string
minlength: 1

All items the customer will be purchasing in this session

quantity integer
format: 1

All items the customer will be purchasing in this session

price number

All items the customer will be purchasing in this session

category string

All items the customer will be purchasing in this session

weight number

Weight of item in mm

height number

Height of item in mm

width number

Width of item in mm

length number

Length of item in mm

position number

Position of the Cart Item in the Cart (calculated internally)

attributes object

Arbitrary properties associated with this item

adjustment array

All items the customer will be purchasing in this session

additionalCosts object

Any costs associated with the session that can not be explicitly attributed to cart items. Examples include shipping costs and service fees.

identifiers array

Identifiers for the customer, this can be used for limits on values such as device ID.

identifiers string

Identifiers for the customer, this can be used for limits on values such as device ID.

attributes object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

responseContent array

Optional list of requested information to be present on the response related to the customer session update. Currently supported: "customerSession", "customerProfile", "coupons", "triggeredCampaigns", "referral", "loyalty" and "event".

Allowed values:

customerSession
customerProfile
coupons
triggeredCampaigns
referral
loyalty
event

#Response Schema

customerSession
integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

couponCodes array

Any coupon codes entered.

couponCodes string

Any coupon codes entered.

referralCode string

Any referral code entered.

state string
default: open

Indicates the current state of the session. All sessions must start in the "open" state, after which valid transitions are...

  1. open -> closed
  2. open -> cancelled
  3. closed -> cancelled
cartItems array

All items the customer will be purchasing in this session

name string
minlength: 1

All items the customer will be purchasing in this session

sku string
minlength: 1

All items the customer will be purchasing in this session

quantity integer
format: 1

All items the customer will be purchasing in this session

price number

All items the customer will be purchasing in this session

category string

All items the customer will be purchasing in this session

weight number

Weight of item in mm

height number

Height of item in mm

width number

Width of item in mm

length number

Length of item in mm

position number

Position of the Cart Item in the Cart (calculated internally)

attributes object

Arbitrary properties associated with this item

adjustment array

All items the customer will be purchasing in this session

additionalCosts object

Any costs associated with the session that can not be explicitly attributed to cart items. Examples include shipping costs and service fees.

identifiers array

Identifiers for the customer, this can be used for limits on values such as device ID.

identifiers string

Identifiers for the customer, this can be used for limits on values such as device ID.

attributes object

A key-value map of the sessions attributes. The potentially valid attributes are configured in your accounts developer settings.

firstSession boolean

Indicates whether this is the first session for the customer's profile. Will always be true for anonymous sessions.

total number

The total sum of cart-items, as well as additional costs, before any discounts applied

cartItemTotal number

The total sum of cart-items before any discounts applied

additionalCostTotal number

The total sum of additional costs before any discounts applied

customerProfile
integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

attributes object

Arbitrary properties associated with this item

accountId integer

The ID of the Talon.One account that owns this profile.

closedSessions integer

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales number

Sum of all purchases made by this customer

loyaltyMemberships array

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivity string
format: date-time

Timestamp of the most recent event received from this customer

eventobject

Event

id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

profileId string

ID of the customers profile as used within this Talon.One account. May be omitted or set to the empty string if the customer does not yet have a known profile ID.

type string
minlength: 1

A string representing the event. Must not be a reserved event name.

attributes object

Arbitrary additional JSON data associated with the event.

sessionId string

The ID of the session that this event occurred in.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

effects array

An array of "effects" that must be applied in response to this event. Example effects include addItemToCart or setDiscount.

ledgerEntries array

Ledger entries for the event.

meta object

Event

campaigns object

Maps each evaluated campaign ID to a key-value list of that campaigns attributes. Campaigns without attributes will be omitted.

coupons object

Maps the coupon value to a key-value list of that coupons attributes.

couponRejectionReason object

Event

referralRejectionReason object

Event

warnings object

Event

loyaltyobject

Loyalty program information

programs object

A map holding information about the loyalty programs balance

referral
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

ID of the campaign from which the referral received the referral code.

advocateProfileIntegrationId string

The Integration Id of the Advocate's Profile

friendProfileIntegrationId string

An optional Integration ID of the Friend's Profile

startDate string
format: date-time

Timestamp at which point the referral code becomes valid.

expiryDate string
format: date-time

Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

code string
minlength: 4

The actual referral code.

usageCounter integer

The number of times this referral code has been successfully used.

usageLimit integer

The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.

couponsarray
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

The ID of the campaign that owns this entity.

value string
minlength: 4

The actual coupon code.

usageLimit integer

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimit number

The amount of discounts that can be given with this coupon code.

startDate string
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDate string
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounter integer

The number of times this coupon has been successfully used.

discountCounter number

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemainder number

The remaining discount this coupon can give.

attributes object

Arbitrary properties associated with this item

referralId integer

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationId string

The Integration ID of the customer that is allowed to redeem this coupon.

importId integer

The ID of the Import which created this coupon.

reservation boolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchId string

The id of the batch the coupon belongs to.

triggeredCampaignsarray
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

applicationId integer

The ID of the application that owns this entity.

userId integer

The ID of the account that owns this entity.

name string
minlength: 1

A friendly name for this campaign.

description string

A detailed description of the campaign.

startTime string
format: date-time

Datetime when the campaign will become active.

endTime string
format: date-time

Datetime when the campaign will become in-active.

attributes object

Arbitrary properties associated with this campaign

state string
default: enabled

A disabled or archived campaign is not evaluated for rules or coupons.

activeRulesetId integer

ID of Ruleset this campaign applies on customer session evaluation.

tags array

A list of tags for the campaign.

tags string
minlength: 1

A list of tags for the campaign.

features array

A list of features for the campaign.

features string

A list of features for the campaign.

couponSettings array
validCharacters array

Set of characters to be used when generating random part of code. Defaults to [A-Z, 0-9] (in terms of RegExp).

couponPattern string
minlength: 3

The pattern that will be used to generate coupon codes. The character # acts as a placeholder and will be replaced by a random character from the validCharacters set.

referralSettings array
validCharacters array

Set of characters to be used when generating random part of code. Defaults to [A-Z, 0-9] (in terms of RegExp).

couponPattern string
minlength: 3

The pattern that will be used to generate coupon codes. The character # acts as a placeholder and will be replaced by a random character from the validCharacters set.

limits array

The set of limits that will operate for this campaign

action string

The limitable action to which this limit will be applied

limit number

The value to set for the limit

entities array

The entities that make the address of this limit

couponRedemptionCount integer

Number of coupons redeemed in the campaign.

referralRedemptionCount integer

Number of referral codes redeemed in the campaign.

discountCount integer

Total amount of discounts redeemed in the campaign.

discountEffectCount integer

Total number of times discounts were redeemed in this campaign.

couponCreationCount integer

Total number of coupons created by rules in this campaign.

lastActivity string
format: date-time

Timestamp of the most recent event received by this campaign.

updated string
format: date-time

Timestamp of the most recent update to the campaign or any of its elements.

createdBy string

Name of the user who created this campaign if available.

updatedBy string

Name of the user who last updated this campaign if available.

effectsarray
createdCouponsarray
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

The ID of the campaign that owns this entity.

value string
minlength: 4

The actual coupon code.

usageLimit integer

The number of times a coupon code can be redeemed. This can be set to 0 for no limit, but any campaign usage limits will still apply.

discountLimit number

The amount of discounts that can be given with this coupon code.

startDate string
format: date-time

Timestamp at which point the coupon becomes valid.

expiryDate string
format: date-time

Expiry date of the coupon. Coupon never expires if this is omitted, zero, or negative.

usageCounter integer

The number of times this coupon has been successfully used.

discountCounter number

The amount of discounts given on rules redeeming this coupon. Only usable if a coupon discount budget was set for this coupon.

discountRemainder number

The remaining discount this coupon can give.

attributes object

Arbitrary properties associated with this item

referralId integer

The integration ID of the referring customer (if any) for whom this coupon was created as an effect.

recipientIntegrationId string

The Integration ID of the customer that is allowed to redeem this coupon.

importId integer

The ID of the Import which created this coupon.

reservation boolean

This value controls what reservations mean to a coupon. If set to true the coupon reservation is used to mark it as a favourite, if set to false the coupon reservation is used as a requirement of usage. This value defaults to true if not specified.

batchId string

The id of the batch the coupon belongs to.

createdReferralsarray
id integer

Unique ID for this entity.

created string
format: date-time

The exact moment this entity was created.

campaignId integer

ID of the campaign from which the referral received the referral code.

advocateProfileIntegrationId string

The Integration Id of the Advocate's Profile

friendProfileIntegrationId string

An optional Integration ID of the Friend's Profile

startDate string
format: date-time

Timestamp at which point the referral code becomes valid.

expiryDate string
format: date-time

Expiry date of the referral code. Referral never expires if this is omitted, zero, or negative.

code string
minlength: 4

The actual referral code.

usageCounter integer

The number of times this referral code has been successfully used.

usageLimit integer

The number of times a referral code can be used. This can be set to 0 for no limit, but any campaign usage limits will still apply.

#

Update a Customer Profile V2

PUT  /v2/customer_profiles/{customerProfileId}

Update (or create) a Customer Profile.

The integrationId may be any identifier that will remain stable for the customer. For example, you might use a database ID, an email, or a phone number as the integrationId. It is vital that this ID not change over time, so don't use any identifier that the customer can update themselves. E.g. if your application allows a customer to update their e-mail address, you should instead use a database ID.

#Example

#Request Schema

URL Parameter

customerProfileId string required

The custom identifier for this profile, must be unique within the account.

Body Parameter

attributes object

Arbitrary properties associated with this item

#Response Schema

customerProfile
integrationId string
format: string

The ID used for this entity in the application system.

created string
format: date-time

The exact moment this entity was created.

attributes object

Arbitrary properties associated with this item

accountId integer

The ID of the Talon.One account that owns this profile.

closedSessions integer

The total amount of closed sessions by a customer. A closed session is a successful purchase.

totalSales number

Sum of all purchases made by this customer

loyaltyMemberships array

A list of loyalty programs joined by the customer

joined string
format: date-time

The moment in which the loyalty program was joined.

loyaltyProgramId integer

The ID of the loyalty program belonging to this entity.

lastActivity string
format: date-time

Timestamp of the most recent event received from this customer

Still need help? Get in touch!
Last updated on 12th May 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