API DOCUMENTATION

Introduction

This API provides an interface to the discfoo promotion engine. There is also a tutorial document and example code avaliable.

To get started you just need to understand the following two methods, Calculate and Redeem.

More documentation will be added in the future to include support for further functionality. Eventually all functionality of the Dashboard will be supported via the API.  

Sandbox Testing

You can use the following credentials to test your connection code in a sandboxed environment:

        cid: 1001

        api: 1234567890ABCDEF1234567890ABCDEF

Support

Please see the Troubleshooting section at the end of this document for solutions to common problems and how to contact us for developer support.

Notes

The API is JSON-only. All data submitted must be encoded in JSON. All responses will be in JSON.

No rate limits apply currently, however we reserve the right to change this at any point in the future.

Successful requests will return HTTP status codes in the 200 or 300 range.

Unsuccessful requests will return HTTP status code 500. Additionally the body will include further information e.g.

{

   "error" : "InvalidSID",

}

Last Updated

18th August 2012

Calculate 

http://api.discfoo.com/calculate

Parameters

See the table below for details about parameters this method accepts:

Discussion

The purpose of this method is to ask the promotion engine to calculate the value of any applicable promotions. To provide context of the customers session in your store, you provide a basic representation of the contents of the cart and transaction.

In response, the promotion engine will return a Session ID and the total value of any applicable promotions. Of course your application will be responsible for deducting the relevant discount from the customers order and/or indicating there is a problem e.g. invalid coupon code.

¹ Each element of the basket array is comprised of associative array with the following keys:

Important: don’t forget to exclude products which should never be discounted e.g. gift vouchers!

² The order parameter is another associative array, with the following key values:

³ The crf parameter does not have to be the actual customer reference, just something unique and consistent e.g. if you identify customer Bob as ‘x123456’ then you should always use this reference when referring to Bob.

Context

In most instances you would make this request during the checkout workflow, typically the order summary page. Another instance would be in response to a customer entering a coupon code. Depending on whether your store is using either automatic promotions and/or coupon based promotions, the context will vary.

In all cases, you will need to retain the Session ID (sid) parameter if the customer completes the order since it is required by the redeem method.  

Example

Here’s an JSON structure we are submitting in our request to the calculate method:

{

   "cid" : "123456",

   "api" : "EA8FC3B6B41B23BAC4928F3607492C984",

   "hmac_sha1" : "m96jHsaVlk6NBNRs93TIwznyFro=",

   "coupon" : "ABC123"

   "basket" : [

      {

         "cat" : "PremiumLego",

         "sku" : "lego1234",

         "val" : 49.99,

         "qty" : "1"

      }

   ],

   "order" :

   {

      "tot" : 49.99,

      "shipping" : "0.00"

   },

}

The response from the server is the following JSON structure:

{

   "sid" : "e3af17",

   "total" : 5.00

}

Redeem 

http://api.discfoo.com/redeem

Discussion

The purpose of this method is to signal to the promotion engine that the Session identified by the Session ID (sid) parameter should be considered complete.

When the promotion engine receives this method call, details about the promotions that were utilised during the calculate method are committed to long-term storage. Additionally, the information concerning the discounted SKUs, order or shipping values are stored for the purpose of reporting in the Dashboard and usage statistics.

Context

In most instances you would make this request soon after the order has been placed. There is no customer feedback as a result of this method so this can be performed by a back-end system if required.

Please note: although there is no strict time limit imposed on how long after the customer order has been placed that this method call is made, it’s strongly recommended to make this request at the earliest possible time to avoid skewed metrics.

Parameters

Example

Here’s an JSON structure we are submitting in our request to the redeem method:

{

   "cid" : "123456",

   "api" : "EA8FC1B6B41B23BAC49E8F3607492C984",

   "sid" : "4fb2cc"

   "oref": "A1234567890"

}

The response from the server is the following JSON structure:

{

   "status" : 1

}

Troubleshooting

If a request returns HTTP Status Code of 500, check the value of the ‘error’ field in the JSON response for a, sometimes, helpful message.

{

   "error" : "Invalid API key",

}

Check that your using a valid “API key” and “CID”. Login in to the Dashboard and go to “Profile” to check these settings. Alternatively, you can use these for testing purposes:

        cid: 1001

        api: 1234567890ABCDEF1234567890ABCDEF

Ensure your requests are encoded in JSON

If you're still having problems let us know, support@discfoo.com Provide a snippet of the relevant code that's causing problems and we will respond as soon as possible, usually within 24hrs.