Skip to main content

API V2.0 ⭐️

The integration API V2 is live, see:

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.

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" : [    [        755,        5352,        0,        [            "setDiscount",            "DISCOUNT",            100        ]    ]]

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.

Additional metadata is returned on-demand#

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 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#

The main steps are:

  1. Adjust your integration to send requests in the API V2 format. See the Integration API.
  2. Rewrite your effects parsing to the new v2 effects format.

Since API V2 is fully backwards compatible with all the data 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 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 payload#

{   "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"   ]}

For more information see the Integration API.