API: Code Validation

Updated 2 years ago by Chris Giddins

Whenever a user attempts to apply a code to the basket, the Validation API is used to determine the validity of the code that has been entered.  It also receives the response that allows the merchant to know which offer to apply to the purchase.

Endpoint: 

https://api.uniqodo.com/validate/API_KEY/PROMO_CODE/MERCHANT

Example API call: 

GET

https://api.uniqodo.com/validate/64a287ae534cf1bd58f45f3e23de9d433caec669/AB12E3GH/1?
email=example@email.com&pos=web&locale=en_GB&baseValidationParam=productId&itemSeparator=;&productId=123ABC;JS123EF&price=50.00;95.99&quantity=1;2&basketTotal=123.45&customerType=new

POST

POST https://api.uniqodo.com/validate/64a287ae534cf1bd58f45f3e23de9d433caec669/AB12E3GH/1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.uniqodo.com
Content-Length: 67
Body: email=example@email.com&pos=web&locale=en_GB&baseValidationParam=productId&itemSeparator=;&productId=123ABC;JS123EF&price=50.00;95.99&quantity=1;2&basketTotal=123.45&customerType=new

Parameters:

Validation Lock

The validation lock feature allows you to lock a valid code to a customer's checkout session ensure the same unique code cannot be used by another customer in a different session. The default lock period is 1 hour during which only one customer can use the code in checkout. The lock period is also configurable in the settings area of your Uniqodo account.

To ensure that the right customer can test their code multiple times (i.e. add the code, remove and add the code back again) you must;

1. keep the validation key in the customer's session and update it each time a code is successfully validated and
2. send the key in the pn parameter for subsequent code validation requests in the same customer session e.g. pn=VALIDATION_KEY. See the example below.

POST https://api.uniqodo.com/validate/64a287ae534cf1bd58f45f3e23de9d433caec669/AB12E3GH/1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: api.uniqodo.com
Content-Length: 67
Body: email=example@email.com&pos=web&locale=en_GB&pn=525c12eb631b60421fb3e64c9bf16

Validation Rule Parameters

The Uniqodo validation rule engine allows rules and further restrictions to be applied to a promotional code based on parameters and values passed to the API.  Restrictions could be arranged around the customer's basket data, for example, as well as any other accessible data item relating to the purchase. 

A rule is created against these parameters when the promotion is set up on the Uniqodo platform. When a code validation API request is made, the validation rule parameters and values are checked against the rule criteria.

... &itemSeparator=;

Example

baseValidationParam=productId&itemSeparator=;&productId=P2322;P2763&price=100.00;50.50&basketTotal=90.50&customerType=new

All other parameters used in the rule must also be supplied. If you have the rule below set up for a promotion,

(basketTotal > 700 AND customerType == 'new')

then both basketTotal and customerType must be supplied as additional request parameters.

Naming Parameters

All parameter names must;

• be alphanumeric but not start with a number
• not contain special characters except underscore (_) and hyphen (-)
• not contain spaces

Response

A successful API call will contain response data under the 'data' key.

{

  "data": {
    "val_key": "525c12eb631b60421fb3e64c9bf161a346a3039e68ec11b86ff11111a65b2691",
    "offer_id": 37,
    "merchant_id": 1,
    "distributor_id": 1,
    "locked_until": null,
    "code": "SAVE25",
    "validated_at": "2018-11-26T20:55:20+0000",
    "discount_amount": 25,
    "discount_type": "percentage",
    "discount_breakdown": [],
    "code_url": "http://www.example.com/",
    "promotion_specific_error": null,
    "tags" : ["PROMOTION_TAG_1", "PROMOTION_TAG_2" ...]
  },

  "errors": [],

}

Product Level Discounts:

The Uniqodo variable discounts functionality allows you to set different discount amounts depending on the items in the customer's basket. The customer only gets issued one single-use unique code which is then used to apply the different levels of discounts to the individual qualifying products in their basket. The applicable rule can be based on product ID, category or any other basket item data like stock levels.

For instance, using the same coupon code, you could offer a 5% discount on TV and 10% discount on mobile phones. In this example, if the customer has a TV and a microwave in their basket then the 5% discount will only apply to the price of the TV as no discount is offered on microwaves. If their basket contains a TV and a mobile phone then 5% will be taken off the price of the TV and 10% off the mobile phone as both are qualifying products. 

When product level discounts are enforced, the code validation response will include the breakdown of all discounts to be applied under the "discount_breakdown" key. Please see the example below.

{
  "data": {
    
    ...

    "code": "EXAMPLE2OFF",
    "validated_at": "2018-11-26T20:55:20+0000",
    "discount_amount": 2,
    "discount_type": "percentage",
    "discount_breakdown": [
       {
            "product_id" : "SKU928289",
            "price": 550.50,
            "discount_amount": 5,
            "discount_type": "percentage",
            "discount_value": 27.53,
            "quantity": 1,
        },
        {
            "product_id": "SKU002751",
            "price": 250.00,
            "discount_amount": 10,
            "discount_type": "percentage",
            "discount_value": 25.00,
            "quantity": 2,
        }
        ...
    ],
    "total_discount_value" : 52.53
    "code_url": "http://www.example.com/",
    "promotion_specific_error": null
  },
  "errors": []
}

Example product level discount rule:

Rules are added when the promotions are set up on the Uniqodo platform.

POST /validate/***********API_KEY_HERE***********/UQDC38BP/1 HTTP/1.1
HOST: api.uniqodo.com
content-type: application/x-www-form-urlencoded
content-length: 110

productId=P111;P7777;P222&quantity=1;2;3&price=29.99;50.50;80.50&itemSeparator=;&baseValidationParam=productId

{
  "data": {
    "id": 6310251,
    "offer_id": 4851,
    "merchant_id": 126,
    "distributor_id": 1,
    "locked_until": null,
    "code": "PROD-LEVEL-DISCOUNT",
    "validated_at": "2019-02-22T09:00:35+0000",
    "discount_amount": null,
    "discount_type": null,
    "total_discount_value": 31.095,
    "trigger_code": "PROD-LEVEL-DISCOUNT",
    "code_url": "http:\/\/www.railcards.co.uk",
    "promotion_specific_error": null,
    "tags": [],
    "discount_breakdown": [{
      "product_id": "p111",
      "price": 29.99,
      "quantity": 1,
      "discount_amount": 0.5,
      "discount_type": "percentage",
      "discount_value": 14.995
     }, {
      "product_id": "p222",
      "price": 80.5,
      "quantity": 3,
      "discount_amount": 0.2,
      "discount_type": "percentage",
      "discount_value": 16.1
    }]
  },
  "errors": [],
  "result": "success"
}

Discount Breakdown Data

Errors (All Merchant APIs):

Error format:

{
  "data": {},
  "errors": [{
    "code": 202,
    "message": "This code has expired and can no longer be used.",
    "promotion_specific_error": null
  }]
}

Codes using validation rules may contain multiple errors depending on the number of violations.

{
  "data": {},
  "errors": [
    {
      "message": "This code is only valid for newly registered customers.",
      "code": 501
    },
    {
      "message": "Your total basket value must be £500 or more to qualify for this discount.",
      "code": 501
    }
    ...
  ]
}

{
  "data": {},
  "errors": [{
    "code": 204,
    "message": "Code not recognised.",
    "reference": ""
  }]
}

How did we do?

Related Articles

• API: Code Redemption
• API: Code Query API
• API Overview