awesome price and product promotions

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:

Name

Condition

Type

Description

cid

required

string

Your Account ID. Login to the Dashboard, click “Profile” to get this value.

api

required

string

Your API key. Login to the Dashboard, click “Profile” to get this value.

coupon

optional

string

A coupon code entered by the customer

basket ¹

required

array of associative arrays

This structure represents the shopping cart contents in detail. See below for more info. Required for Product type promotions.

order ²

required

associative array

This structure contains anonymous information related to the order. Required for Order/Shipping type promotions.

crf ³

optional

string

This value is used for determining conditions related to the  “Maximum Use - per Customer setting.

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:

Name

Condition

Type

Description

cat

required

string

The primary Category the SKU relates to

sku

required

string

The unique identifier for a product

val

required

string

Monetary value of a single SKU

qty

required

string

The total number of SKU’s of this type in the basket

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:

Name

Condition

Type

Description

tot

required

number

The total value of this order

shipping

optional

number

The shipping value of this transaction

³ 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:

Name

Type

Description

sid

string

Session ID

total

number

The total value of any promotions applied in the session

{

   "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

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

Name

Condition

Type

Description

cid

required

string

Your Account ID. Login to the Dashboard, click “Profile” to get this value

api

required

string

Your API key. Login to the Dashboard, click “Profile” to get this value

sid

required

string

A valid Session ID returned from the Calculate method

oref

optional

string

Optionally, supply a reference created by your store (max length 32 chars)

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:

Name

Type

Description

status

number

A numeric status code which indicates either success (1) or failure (0) of the method

{

   "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.