API V2.0

API V2.0 is live

• See the Update a Customer Session specifications.
• See the new effect specifications

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.

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