API V2.0

API V2.0 is live
Introducing a new API version
Talon.One has received a lot of feedback and ideas for improvement in the last 3 years.
Most 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 the customer session integration API
endpoint.
Main improvements in Integration API V2
Effects become structured JSON objects
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, we have 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
}
]
Additional costs
The API currently allows you to send cart items and a session total. Soon will also
allow for a structured, built-in way of communicating all the other fees associated
with a purchase. The AdditionalCosts
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 want to see in the response.
We currently support:
- The evaluated coupon
- The evaluated referral code
- All triggered campaigns
- The customer profile
Additionally, any referral or coupon codes that were generated as an effect will always
be returned in full.
Multiple coupons per session
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.
Cascading discounts
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 awarded discounts into consideration. This means a 100EUR order that triggered 2 different 10% discounts will see a total discount of 10EUR + 9EUR, and not 10EUR + 10EUR anymore.
Concepts that didn't change
The general flow and behaviour of updating customer sessions is the same as v1. You
send us the shopping cart and other relevant session data, and we respond with the
triggered effects.
How you create and manage campaigns doesn't change, and all your existing coupons,
customer sessions, customer profiles and campaigns are already compatible with API V2.
Migrating to V2
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's 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 rules that
trigger when a coupon is valid and rules that do not depend on the presence
of a coupon, must be split to allow the coupon use cases to be isolated in a
single campaign.
Contact our customer success team if you have more questions on this topic.
Example request
{
"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"
]
}
Example response
{
"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
}
]
}
Last updated on 24th Feb 2021