We've received a lot of feedback and ideas for improvement in the three years since we launched Talon.one. Many of the smaller-scope ideas have already been implemented, such as coupon rejection reasons, returning attributes of coupons and campaigns, as well as many new types of effects. In order to implement the larger improvements without breaking backward compatibility, we're happy to announce v2 of our customer session integration API endpoint.
In API v1, each effect was returned as an array of strings, containing arrays of even more strings. Such as this discount effect for example:
"Effects" : [
[
755,
5352,
0,
[
"setDiscount",
"DISCOUNT",
100
]
]
]In API V2 however, we have completely redesigned the effects response. Effects are now properly structured JSON Objects. This makes parsing them way more transparent, and their meaning is more self-explanatory:
"effects": [
{
"campaignId": 755,
"effectType": "setDiscount",
"props": {
"name": "DISCOUNT",
"value": 100
},
"ruleIndex": 0,
"ruleName": "100€ Discount",
"rulesetId": 5352
}
]Our API currently allows you to send Cart Items and a Session Total, and soon will also allow for a structured, built-in way of communicating all the other fees associated with a purchase. The “Additional Costs” section:
"additionalCosts": {
"fees": {
"price": 3.5
},
"shipping":{
"price": 5
}
}Now you can define and communicate all additional costs, such as shipping and processing fees, in a structured way.
By default, our integration response is much smaller now. Under normal circumstances, we only return the event with all its effects. For most use cases, this is also all this is needed. Stripping all unnecessary data from the response allows us to optimize performance and reduces the amount of space logs will take on your (and our) system.
Does your integration require more than just the “naked” effects? In that case, you can optionally specify which other entities you would like to see in the response.
We currently support:
Additionally, any referral- or coupon codes that were generated as an effect will always be returned in full.
In API V2, the field for the coupon code will be replaced with an array. This means you will be able to send multiple coupon codes in one session.
The addition of “additional costs” and rules that enforce session total = sum of all cart items + all additional costs, will allow us to support cascading discounts. This means that soon, under API v2, percentage discounts on the session total or on cart items will take any previously awarded discounts into consideration. This means a 100EUR order that triggered 2 different 10% discounts will see a total discount of 10EUR + 9 EUR, and not 10EUR + 10EUR like now.
The general flow and behaviour of updating customer sessions is identical to v1. You send us the shopping cart and other relevant session data, and we respond with the triggered effects, just like before.
Nothing changes about how you create and manage campaigns, and all your existing coupons, customer sessions, customer profiles and campaigns are already compatible with API V2.
On a technical level, you will need to adjust your integration to send requests in the API v2 format, and rewrite your effects parsing to the new v2 effects format.
Since API V2 is fully backwards compatible with all data that is currently stored in your Talon.One database, you can switch to v2 whenever you like. Even sessions created under v1 can be edited and cancelled using API v2.
The only other consideration to make is when you also want to switch your older integration to support multiple coupons. Older campaigns that contain both rules that trigger when a coupon is valid in addition to rules that do not depend on the presence of a coupon, will need to be split up so that the coupon use cases get isolated in a single campaign. Do not hesitate to contact our customer success team if you have more questions on this topic.
{
"customerSession":{
"additionalCosts":{
"delivery":{
"price":3.5
},
"handling":{
"price":5
}
},
"cartItems":[
{
"name":"pizza",
"price":1,
"quantity":2,
"sku":"SKU-123"
}
],
"profileId":"Max",
"state":"closed",
"attributes":{
"ShippingMethod": "Standard",
"PaymentMethod": "creditcard"
}
},
"responseContent":[
"customerSession",
"customerProfile",
"coupons",
"referral",
"loyalty",
"event",
"triggeredCampaigns"
]
}{
"coupons":[
],
"createdCoupons":[
],
"createdReferrals":[
],
"customerProfile":{
"accountId":400,
"attributes":{
},
"closedSessions":2,
"created":"2020-02-28T09:41:52.853668Z",
"integrationId":"max",
"lastActivity":"2020-02-28T11:41:53.069537+02:00",
"loyaltyMemberships":null,
"totalSales":19
},
"customerSession":{
"additionalCostTotal":0,
"additionalCosts":{
"delivery":{
"price":3.5
},
"handling":{
"price":5
}
},
"applicationId":334,
"cartItemTotal":0,
"cartItems":[
{
"name":"pizza",
"position":0,
"price":1,
"quantity":2,
"sku":"SKU-123"
}
],
"created":"2020-02-28T11:41:53.045514+02:00",
"firstSession":false,
"integrationId":"session2",
"profileId":"max",
"state":"closed",
"total":9.5
},
"effects":[
{
"campaignId":231,
"effectType":"setDiscount",
"props":{
"name":"foo",
"value":1
},
"ruleIndex":0,
"ruleName":"Always give a discount",
"rulesetId":122
}
],
"event":{
"applicationId":334,
"attributes":{
"integrationId":"session2",
"isNew":true,
"params":{
"additionalCosts":{
"delivery":{
"price":3.5
},
"handling":{
"price":5
}
},
"cartItems":[
{
"name":"pizza",
"position":0,
"price":1,
"quantity":2,
"sku":"SKU-123"
}
],
"profileId":"max",
"state":"closed"
}
},
"created":"2020-02-28T11:41:53.053722+02:00",
"effects":[
[
231,
122,
0,
[
"setDiscount",
"foo",
1
]
]
],
"id":521,
"ledgerEntries":[
],
"profileId":"max",
"sessionId":"session2",
"type":"talon_session_closed"
},
"loyalty":{
"programs":{
}
},
"referral":null,
"triggeredCampaigns":[
{
"activeRulesetId":122,
"applicationId":334,
"attributes":{
},
"created":"2020-02-28T09:41:52.083892Z",
"description":"",
"features":[
],
"id":231,
"limits":[
],
"name":"Campaign et",
"state":"enabled",
"tags":[
],
"updated":"2020-02-28T09:41:52.58376Z",
"updatedBy":"Admin",
"userId":400
}
]
}If you’d like a member of our support team to respond to you, please send a note to support@talon.one