24th Mar 2020

API V2.0

Banner

  • Work in progress
  • Release
  • Multiple coupons
  • Cascading discounts

API V2.0 went live

  • The new "Update a Customer Session" specifications can be found here
  • The new effect specifications can be found here
  • Currently supported SDKs: JavaScript / Node.js

Why we are introducing a new API version

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.

Main improvements in Integration API V2

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

Additional costs

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.

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 would like 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 (coming soon)

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 (coming soon)

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.

What does not change

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.

How to migrate

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.

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
      }
   ]
}
Still need help? Get in touch!
Last updated on 24th Mar 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