Rehook Platform API provides resource oriented URLs to work with your business data. Our API uses JSON for request and response. API errors are returned using standard HTTP response codes.

Introduction

Validate coupon API will enable you to validate an applied coupon code for it's redemption or applicability. Your application can consume this API at applicable touch points on your app or web.

On successful API call, Rehook will validate the coupon code and returns with a response body which specifies whether applied coupon code can redeemed or not.

You can consume this API on following cases:

1. When customer apply the coupon code on cart.
2. When customer entered the coupon code manually.
3. When customer modify the cart details after applying the coupon.
4. or any other check point as per your application purchase journey.

API details

API Endpoint: https://api.rehook.ai/coupons/validate

HTTP Method: POST

Prerequisites

1. API Key and Secret Key for your application
2. If you don't know the API key and secret key, please go to setting module on admin panel to view API details for your application. To know more about application setting, please visit Application setting
3. API key and secret key are auto generated and cannot be changed.

Authentication

You need to provide the API key and Secret of your application in every new request as Authorization. Rehook use Basic authentication method to authenticate the API calls.

Parameters

Query Parameters

This API doesn't requires any query parameters. you have to provide the details in API body.

Body Parameters

Please refer to the complete request body as given below.

{
    "coupon_details": [
        {
            "coupon_id":"coupm_tfKRcTxedjr17FH3m267V",
            "coupon_code":"KS"
        }
    ],
    "source_id":"krish123",
    "order": {
        "order_id": "1223456",
        "status": "pending",
        "original_price_subtotal": 800,
        "selling_price_subtotal": 800,
        "shipping": 100,
        "tax":20,
        "payment_mode": "UPI",
        "metadata": {
            "cart_qty": "4"
        },
        "items": [
            {
                "product_id": "123",
                "sku": "",
                "name":"",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand A",
                    "category": "grocery"
                }
            },
             {
                "product_id": "654",
                "sku": "",
                "name":"",
                "brand": "wrangler",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 2,
                "shipping": 0,
                "metadata": {
                    "brand": "brand B",
                    "category": "vegetables"
                }
            }
        ]
    }
}

Parameters without an object (Optional)

Order details object (Optional)

Item details - Array of object (Optional)

Coupon details object(Mandatory)

Meta data (Optional)

You can provide the meta data in order object or item object using key value pair

Example:

📘

Meta data -limitation

1. Meta data details are optional in the request body.
2. If you want to pass any other custom fields in the API payload, then such fields can be passed as key value pairs inside metadata object.
3. Our system will validate the meta data only if same meta data with key value pair with same data type is created in any campaign on rebook dashboard, otherwise, Rehook API will nullify the meta data provided in the request body.
4. Meta data object can be passed at order or item level.

Sample request body

Below table shows what details to be shared in the request body in following cases.

Sample request body and API behaviour details are given below for the above mentioned cases:

Complete payload and response

Complete request body:

{
    "coupon_details": [
        {
            "coupon_id":"coupm_tfKRcTxedjr17FH3m267V",
            "coupon_code":"KS"
        }
    ],
    "source_id":"krish123",
    "order": {
        "order_id": "1223456",
        "status": "pending",
        "original_price_subtotal": 800,
        "selling_price_subtotal": 800,
        "shipping": 100,
        "tax":20,
        "payment_mode": "UPI",
        "metadata": {
            "cart_qty": "4"
        },
        "items": [
            {
                "product_id": "123",
                "sku": "",
                "name":"",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand A",
                    "category": "grocery"
                }
            },
             {
                "product_id": "654",
                "sku": "",
                "name":"",
                "brand": "wrangler",
                "original_price": 200,
                "selling_price": 200,
                "quantity": 2,
                "shipping": 0,
                "metadata": {
                    "brand": "brand B",
                    "category": "vegetables"
                }
            }
        ]
    }
}

📘

API Behaviour:

• Above payload contains the complete details of API payload for coupon validation
• For assigned user coupons, passing source_id is mandantory, otherwise system will return error message asking user to login to redeem the coupon code
• In coupon details object, you have to share either coupon code or coupon id. Rehook will validate the coupon code if any of the fields are correct.
• Coupon details are mandatory in the validation API call
• For bulk user coupon - same coupon code can be passed in coupon_code and coupon_id fields.
• Order object and Item object are optional, please provide the mandatory details of order and item if you want to validate the coupon codes based on cart and item validations.
• All other parameters in cart validations and product validations is optional.
• If you don't want to perform any validations on cart to item, then just provide coupon details in the request body with or without source_id based on logged in status.
• If validation is applied on mandatory parameters and such parameters are not passed in the request body, API will return the validation error messages.
• If validation is applied on optional parameters and parameters are not passed in the request body, API will not return error, however validation error is only returned when optional parameters are passed.
• If you want to pass any other custom fields in the API payload, then such fields can be passed as key value pairs inside metadata object.
• We suggest you to pass the order and item object in all the API calls to avoid fraud coupon redemption.

case 1: Response body with validation is true

{
    "coupon_code": "SELECTED",
    "coupon_code_id": "coupm_5lzR4H2wRja7sVGzZ9HOV",
    "coupon_name": "selected items",
    "coupon_terms_and_conditions": [
        ""
    ],
    "is_applicable": true,
    "coupon_savings": {
        "order": {
            "order_id": "1223456",
            "source_id": "KMN@123",
            "status": "pending",
            "original_price_subtotal": 800,
            "selling_price_subtotal": 800,
            "total_discount": 100,
            "discount_calculated_on_property": "selected_items_selling_price_subtotal",
            "total_amount": 700,
            "total_cashback": 0,
            "shipping": 100,
            "payment_mode": "UPI",
            "coupon_details": {},
            "metadata": {
                "cart_qty": "4"
            },
            "items": [
                {
                    "discount_value": 100,
                    "final_amount": 100,
                    "metadata": {
                        "brand": "brand A",
                        "category": "grocery"
                    },
                    "name": "",
                    "original_price": 200,
                    "product_id": "123",
                    "quantity": 1,
                    "selling_price": 200,
                    "shipping": 0,
                    "sku": ""
                },
                {
                    "brand": "wrangler",
                    "discount_value": 0,
                    "final_amount": 400,
                    "metadata": {
                        "brand": "brand B",
                        "category": "vegetables"
                    },
                    "name": "",
                    "original_price": 200,
                    "product_id": "654",
                    "quantity": 2,
                    "selling_price": 200,
                    "shipping": 0,
                    "sku": ""
                }
            ]
        }
    },
    "request_id": "c1a9dd45-a8b7-97be-a846-def9a0e18ddc"
}

case 2: response body when validation is false

{
    "coupon_code": "WHOLECART",
    "coupon_code_id": "coupm_9ZbJ2ryi4ia2eyz6I7sRc",
    "coupon_name": "WHOLE CART",
    "coupon_terms_and_conditions": [
        ""
    ],
    "is_applicable": false,
    "message": "selling_price_subtotal should be greater than 3000.00",
    "coupon_savings": {
        "order": {
            "order_id": "",
            "source_id": "",
            "status": "",
            "selling_price_subtotal": 0,
            "total_discount": 0,
            "total_amount": 0,
            "total_cashback": 0,
            "shipping": 0,
            "coupon_details": {}
        }
    },
    "request_id": ""
}

sample response fields and definition

Discount_calculated_on_property - value and definition

When customer is logged in

case 1: Without any validations

{
		"source_id": "101",
		"coupon_details": [{
			"coupon_id": "XYZ",
			"coupon_code": "RVKAC"
		}]
}

📘

API Behaviour:

• If you want to validate coupon code applicable for a logged in customer without any validation on cart or item, you just need to provide the source_id and coupon details in the API request body.
• For above payload, Rehook API will validate the coupon code for given source id returns validity status with coupon details for it's redemption.

case 2: With cart or item validations

Refer to complete payload

📘

API Behaviour:

• If you want to validate coupon code applicable for a logged in customer with additional validation on cart or item, you need to provide the source_id, coupon details and order or item object with mandatory fields in the API request body.
• With reference to above payload, Rehook will validate the source_id = 101 with coupon code or coupon_id and perform validation check on cart or item object and returns the validity status with coupon details for it's redemption.

For not signed in customers

Case 1: without any validations

{
	"coupon_details": [{
		"coupon_id": "XYZ",
		"coupon_code": "RVKAC"
	}]
}

📘

API Behaviour:

• If you want to validate the coupon code for a not signed customers, you have to pass only coupon_details in the request body
• In this case, Rehook API will validate only given coupon code available for your applications without checking any validations on customer/order/Item and returns validity status with coupon details.

Case 2: with order/item validations

Refer to complete payaload without source_id 	

📘

API Behaviour:

• If you want to validate the coupon code for a not signed customers with cart or item validation while customer is active on your cart page, you have to pass the coupon details and cart or item object without source_id
• With reference to above payload, Rehook will validate only coupon code and perform additional validation on cart or item object and returns coupon validity status with coupon details for it's redemption.

Discount types:

Whole cart

In whole cart discount type, discount will be applied on whole cart. you can apply discount on following properties with cart or product validations.

1. Selling_price_subtotal
2. original_price_subtotal
3. shipping

Example: Buy min worth of Rs 5000 and Get Flat 30% off on MRP.

Expected payload

{
    "coupon_details": [
        {
            "coupon_id":"coupm_tfKRcTxedjr17FH3m267V",
            "coupon_code":"FLAT50"
        }
    ],
    "source_id":"krish123",
    "order": {
        "order_id": "1223456",
        "status": "pending",
        "original_price_subtotal": 6400,
        "selling_price_subtotal": 6400,
        "shipping": 100,
        "tax":20,
        "payment_mode": "UPI",
        "metadata": {
            "cart_qty": "4"
        },
        "items": [
            {
                "product_id": "123",
                "sku": "",
                "name":"",
                "original_price": 3200,
                "selling_price":3200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand A",
                    "category": "grocery"
                }
            },
             {
                "product_id": "654",
                "sku": "",
                "name":"",
                "brand": "wrangler",
                "original_price": 3200,
                "selling_price": 3200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand B",
                    "category": "vegetables"
                }
            }
        ]
    }
}

📘

API Behaviour for above payload

1. In the payload, you have to pass the item details and order details for discount validations associated with a coupon code
2. In above example, discount to be applied on whole cart MRP (original_price_subtotal) when customer buys min order worth of Rs 5000 (this validation can be done on MRP or selling price based on configuration)
3. with above payload, Rehook will first check for discount validation on min order worth of 5000. since MRP or selling_price_subtotal is Rs 6400 which is greater than 5000, coupon validation is true
4. 30% discount will be applied on original_price_subtotal as per the configuration.
5. In response, system will return the following keys in the order object
   a. total_discount : discount amount calculated (in this case, it will be 30 % of original_price_subtotal )
   b. total_amount: selling_price_subtotal - total_discount
   c. discount_calculated_on_property : indicates on which property discount to be applied on
6. When whole cart discount is applied, total discount is returned in the order object. item level discount will not be returned.
7. In above payload, if order worth is less than 5000, then Rehook will return discount applicability as false

Whole cart excluding

In this type, discount will be applied on whole cart by excluding specified product properties with cart or product validations.

example: Buy products worth Rs 5000 and Get 50% off on whole cart, discount is not applicable for items from tobaco category

expected payload:

{
    "coupon_details": [
        {
            "coupon_id":"coupm_tfKRcTxedjr17FH3m267V",
            "coupon_code":"FLAT50"
        }
    ],
    "source_id":"krish123",
    "order": {
        "order_id": "1223456",
        "status": "pending",
        "original_price_subtotal":9600,
        "selling_price_subtotal":9600,
        "shipping": 100,
        "tax":20,
        "payment_mode": "UPI",
        "metadata": {
            "cart_qty": "4"
        },
        "items": [
            {
                "product_id": "123",
                "sku": "",
                "name":"",
                "original_price": 3200,
                "selling_price":3200,
                "quantity": 2,
                "shipping": 0,
                "metadata": {
                    "brand": "brand A",
                    "category": "grocery"
                }
            },
             {
                "product_id": "654",
                "sku": "",
                "name":"",
                "brand": "wrangler",
                "original_price": 3200,
                "selling_price": 3200,
                "quantity": 1,
                "shipping": 0,
                "metadata": {
                    "brand": "brand B",
                    "category": "tobaco"
                }
            }
        ]
    }
}

📘

API behaviour

1. In the payload, you have to pass the item details and order details for discount validations associated with a coupon code

2. In this example, discount will be applied on valid cart subtotal (MPR or selling price based on the configuration). system will not apply discount on products from tobaco category

3. with above payload, Rehook will first check for discount validation on min order worth of 5000. since MRP or selling_price_subtotal is Rs 6400 which is greater than 5000, discount validation is true

4. To apply discount, rehook will first calculate the valid cart subtotal (Eligible items selling price or original price * quantity). In above example, only SKU: 123 is considered in the valid cart as SKU: 654 is from tobaco category which is to be excluded.

5. Hence, valid cart subtotal will be = selling price or orginal price of sku 123 quantity (3200 2) = 6400

6. Now, 50% discount will be applied on valid cart subtotal

7. In response, system will return the following keys in the order object.

   a. total_discount : discount amount calculated (in this case, it will be 30 % of original_price_subtotal )
   b. total_amount: selling_price_subtotal - total_discount
   c. discount_calculated_on_property : In this case, value will be valid_cart_selling_price_subtotal or
   valid_cart_original_price_subtotal

8. In response, system will return the following keys in the item object
   a. discount_value: item level discount amount. this value will exist only for applicable items. excluded
   items will have discount_value as zero. system will first calculate the total discount
   on valid cart, then distribute discount amount at item level based on it's GMV
   b. final_amount: (Selling_price quantity) - discount_value : in above example, final_amount will be
   (3200 * 2 ) - discount_value

Sample response body for above example:

{
    "coupon_code": "EXCLUDE",
    "coupon_code_id": "coupm_0EgJoMmnd2vzbhXAQGsZH",
    "coupon_name": "Exclude items",
    "coupon_terms_and_conditions": [
        ""
    ],
    "is_applicable": true,
    "coupon_savings": {
        "order": {
            "order_id": "1223456",
            "source_id": "KMN@123",
            "status": "pending",
            "original_price_subtotal": 9600,
            "selling_price_subtotal": 9600,
            "total_discount": 3200,
            "discount_calculated_on_property": "valid_cart_selling_price_subtotal",
            "total_amount": 6400,
            "total_cashback": 0,
            "shipping": 100,
            "payment_mode": "UPI",
            "coupon_details": {},
            "metadata": {
                "cart_qty": "4"
            },
            "items": [
                {
                    "discount_value": 3200,
                    "final_amount": 3200,
                    "metadata": {
                        "brand": "brand A",
                        "category": "grocery"
                    },
                    "name": "",
                    "original_price": 3200,
                    "product_id": "123S",
                    "quantity":2,
                    "selling_price": 3200,
                    "shipping": 0,
                    "sku": ""
                },
                {
                    "brand": "brand b",
                    "discount_value": 0,
                    "final_amount": 400,
                    "metadata": {
                        "brand": "brand B",
                        "category": "tobacco"
                    },
                    "name": "",
                    "original_price": 200,
                    "product_id": "654S",
                    "quantity": 2,
                    "selling_price": 200,
                    "shipping": 0,
                    "sku": ""
                }
            ]
        }
    },
    "request_id": "82eb1f97-f5a8-9d9d-b032-0e16a120bd62"
}

Selected items

In this type, discount will be applied on selected items having specified product properties. selected items discount can be configured in following ways:

Selected items validations:

Rehook supports validations on selected items property

Success Response:

If API call is successful, then Rehook will return the following HTTP success code with response body as given below:

Error Responses

If API call is failed, then Rehook will return the following HTTP success code with response body as given below:

error response body

Below table shows possible list of cases with error messages