Overview

The Validate Coupon API enables you to verify the validity and applicability of a coupon code users enter during the checkout process. Verifying the coupon details with cart and product metadata ensures accurate discounts and a seamless shopping experience.

You can integrate this API at relevant touchpoints within the application or website. Upon successful validation, CleverTap validates if the coupon code is redeemable and returns the result in a structured response.

You can use this API in the following cases:

When the user applies the coupon code on the cart.
When a user enters the coupon code manually.
When a user modifies the cart details after applying the coupon.
Any other custom checkpoints in the user journey while completing a transaction.

Base URL

Here is an example base URL from the account in the India region:

https://in1.api.clevertap.com/1/validate-coupon.json

@Bajrang correct endpoint: https://in1.api.clevertap.com/1/promo/coupons/validate

Region

To identify the API endpoint for the region of your account, refer to Region.

Headers

For more information about API headers used while processing API requests, refer to Headers.

HTTP Method

POST

Query Parameters

Parameter	Description	Required/Optional	Type	Sample Value
`identity`	The unique identifier for the user. This is mandatory for campaign user coupon validation to determine the source of the coupon issued.	Optional for All Users Coupon and Required for Campaign Users Coupon	String	`user123`

📘
Identity Not Passed
When Identity is not passed for the campaign user coupon, the system returns an error message indicating the missing identity or prompts the user to log in to redeem the coupon code.

Body Parameters

The body parameters define the structure and data required to validate a coupon. These parameters include key objects that provide information about the coupon, the associated order, items, and other contextual details necessary for the API to process the validation request.

`coupon` Object

The coupon object contains couponID and couponCode for validating a coupon. Depending on the type of coupon, it includes either a coupon ID or coupon code, which is used to process and apply the coupon in various redemption scenarios.

Parameter	Description	Required/Optional	Data Type	Sample Value
`couponId`	Coupon ID generated against a coupon code.	Optional	String	`coupon_123`
`couponCode`	Unique coupon code to be validated.	Required	String	`DIWALI100`

📘
Coupon ID and Coupon Code Handling
Coupon codes must be alphanumeric and are case-sensitive (must be entered in ALL CAPS). Ensure the codes follow the standard format defined during the setup process to avoid validation errors.
The following are the conditions and their system handling for the couponId and couponCode:

For Fixed Code Coupons: For fixed codes, you can provide either a couponCode or a couponID. If both parameters are provided, the system validates the coupon using either one, as long as one of them is correct.

For Bulk Code Coupons: For bulk codes, you must provide the coupon code. The coupon ID and coupon code can have the same value, but the system only validates the coupon based on the provided couponCode. If the couponCode is invalid or not found, the system returns an error.

`order` Object

The order object provides information about the overall order and is a mandatory parameter. If the order object is not included, the API cannot validate the coupon effectively, as the coupon applicability and calculations depend on these order details.

Parameter	Description	Required/Optional	Data Type	Sample Value
`orderId`	Unique ID for the order being placed. This ID is used to track transactions and associate them with a specific purchase. For example, if a user is buying a shirt, the `orderId` can be `abcd12345`.	Required	String	`abcd12345`
`saleMrpTotal`	Sum of the original price of all items, calculated as `MRP` x `quantity`	Optional	Numeric	`500`
`saleAmount`	Sum of the selling price of all items, calculated as`unitPrice` x `quantity`	Required	Numeric	`300`
`saleChannel`	Source through which the sale is done.	Optional	String	`online`
`location`	Location of the sale made.	Optional	String	`India`
`locationId`	Unique ID assigned to a location.	Optional	String	`IND`
`orderShipping`	Sum of shipping charges at an order level.	Optional	Numeric	`30`
`orderStatus`	Indicates the current status of the transaction. This status is primarily managed within the user application and provides context for coupon redemption and transaction flow: Pending: The order is initiated but not yet completed. Completed: The order is successfully completed. Reverted: The order is rolled back, and the coupon redemption is undone.	Optional	String	`pending`
`paymentMode`	Mode of payment used for the transaction. For example,`credit_card`, `debit_card`, `net_banking` and so on.	Optional	String	`credit_card`
`cartQuantity`	Total quantity of items in the cart.	Optional	Numeric	`4`

`item` Object

The item object provides details about individual items in the cart and is a mandatory parameter for coupon validation. If the item object is not included, the API cannot process the validation correctly, as it relies on item-specific information such as productId, unitPrice, and quantity to validate and apply coupons.

Parameter	Description	Required/Optional	Data Type	Sample Value
`productId`	Unique identifier for the product in the application.	Required	String	`abc_124`
`sku`	Stock Keeping Unit (SKU) assigned to a product in the application.	Optional	String	`124`
`itemName`	Name of the product.	Optional	String	`Coke`
`category`	Name of the product category.	Optional	String	`shirts`
`subCategory`	Name of the product subcategory.	Optional	String	`cotton shirts`
`brand`	Name of the product brand.	Optional	String	`superdry`
`unitPrice`	Selling price of the product.	Required	Numeric	`80`
`mrp`	MRP of the product.	Optional	Numeric	`700`
`quantity`	Quantity of the product in the cart.	Required	Numeric	`12`

📘
order and item Object Validation
The following

If the order and item objects are not passed, the API returns an error message indicating missing order or item objects.

If the mandatory keys for the order and item objects are missing, the API returns an error message indicating the missing mandatory keys.

If the mandatory keys for the order and item objects are passed but contain empty values, the API returns an error message indicating the invalid input.

If the complete order and item object details are passed, the API validates the coupon based on the cart or product properties. It returns the applicability status, either true or false, along with a validation message.

`metadata` Object

The metadata object allows you to include additional custom key-value pairs for advanced coupon validations.

Parameter	Description	Required/Optional	Data Type	Sample Value
`key`	Metadata property name (for example, color, size, supplier).	Optional	Object	`size`
`value`	Metadata property value (for example, Red, Large, Supplier A).	Optional	Object	`large`

Sample Request

{   
    "coupon": {
        "couponid": 1081 ,
        "couponCode": "FLAT99"
    },
    "order": {
        "orderId": "wwww123",
        "saleMrpTotal": 5000,
        "saleAmount": 2000,
        "saleChannel": "ONLINE",
        "location": "India",
        "locationId": "IND",
        "orderShipping": 0,
        "orderStatus": "success",
        "metadata": {
            "key1": "value 1",
            "key2": "value 2"
        },
        "items": [
            {
                "productId": "abc_124",
                "sku": "124",
                "itemName": "i1",
                "category": "electronics",
                "subCategory": "B1",
                "brand": "B1",
                "originalPrice": 500,
                "unitPrice": 200,
                "mrp": 100,
                "quantity": 2,
                "metadata": {
                    "category": "drinks",
                    "expiryDate": "2024-12-31"
                }
            },
            {
                "productId": "xyz_456",
                "sku": "456",
                "itemName": "Jeans",
                "category": "fashion",
                "subCategory": "pants",
                "brand": "Superdry",
                "Item_Type" : "Bottle",
                "originalPrice": 20,
                "unitPrice": 20,
                "mrp": 40,
                "quantity": 1,
                "metadata": {
                    "color": "blue",
                    "size": "32"
                }
            }
        ]
    }
}

Sample Response

{
    "status": "success",
    "records": [
        {
            "couponTimeframe": [
                {
                    "timeSlot": {
                        "startTime": "1740642505",
                        "endTime": "1840642505"
                    },
                    "validationDay": "All"
                }
            ],
            "couponName": "FLAT100",
            "couponExpiry": 1740835113,
            "couponCodeId": 1081,
            "totalRedemptionUnlimited": false,
            "isApplicable": true,
            "description": "This order is applicable on order above $100",
            "message": "",
            "termsAndConditions": [
             "terms and condition 1"
             "terms and condition 2",
                                  ],
            "discountEffect": {
                "discountRate": 99,
                "rewardType": "discount",
                "discountType": "entireOrder",
                "discountAppliedOn": "saleAmount",
                "discountValue": "absolute"
            },
            "totalRedemptionLeft": 18,
            "couponSavings": {
                "customPropertyDiscount": null,
                "orderDiscount": 100,
                "shippingDiscount": 0,
                "orderCashbackPoints": 0,
                "order": {
                    "saleAmount": 2000,
                    "orderNetAmount": 1901,
                    "metadata": {
                        "paymentMethod": "credit card",
                        "promoCode": "NEWYEAR"
                    },
                    "saleMrpTotal": 5000,
                    "orderId": "wwww123",
                    "orderStatus": "success",
                    "saleChannel": "online",
                    "orderShipping": 0,
                    "locationId": "IND",
                    "location": "India",
                    "items": [
                        {
                            "unitPrice": 200,
                            "subCategory": "B1",
                            "metadata": null,
                            "quantity": 5,
                            "productId": "abc_124",
                            "itemDiscount": 94.29,
                            "mrp": 100,
                            "itemCashbackPoints": 0,
                            "grossAmount": 400,
                            "itemName": "i1",
                            "grossMrp": 200,
                            "sku": "124",
                            "category": "electronics",
                            "itemNetAmount": 305.71,
                            "brand": "B1"
                        },
                        {
                            "unitPrice": 20,
                            "subCategory": "pants",
                            "metadata": null,
                            "quantity": 1,
                            "productId": "xyz_456",
                            "itemDiscount": 4.71,
                            "mrp": 40,
                            "itemCashbackPoints": 0,
                            "grossAmount": 20,
                            "itemName": "Jeans",
                            "grossMrp": 40,
                            "sku": "456",
                            "category": "fashion",
                            "itemNetAmount": 15.29,
                            "brand": "Superdry"
                        }
                    ],
                }
            },
            "bestCoupon": "false",
            "identity": "User-2",
            "requestId": "1234",
            "redemptionActivationDate": 1740835113,
            "userRedemptionUnlimited": false,
            "redemptionStatus": true,
            "couponCode": "FLAT99",
            "userRedemptionLeft": 2
        }
    ]
}

Understanding API Responses

The API response varies depending on the input payload, metadata, coupon configuration, and user identity. The following are the specific scenarios and their corresponding expected outcomes:

Scenario	Behavior
Optional parameters validation	If validation rules apply to optional parameters that are not provided in the request, the API still validates them and returns an error message.
Metadata validation	If you include custom fields in the API payload, these fields must be provided as key-value pairs within the metadata object of the `order` or `item` object. The API validates the metadata properties set in the coupon. It returns the applicability status, either `true` or `false` and a validation message, regardless of whether metadata details are passed.
Coupon code or coupon ID validation
Coupon details not provided	The API returns an error message indicating that coupon details are mandatory.
Coupon expiration	The API returns an error message indicating the coupon is expired.
Day-specific coupon availability	If a coupon is not valid on certain days, the API behaves as defined in the Fetch Coupon API.
Case-sensitive coupon codes	The API ignores case sensitivity for coupon code validation. For example, `KMN123` and `kmn123` are both considered valid codes.

Errors

To know about the errors applicable to the Validate Coupon API, refer to API Error Cases.

Validate Coupon

Overview

Base URL

Region

Headers

HTTP Method

Query Parameters

📘
Identity Not Passed

Body Parameters

`coupon` Object

📘
Coupon ID and Coupon Code Handling

`order` Object

`item` Object

📘
`order` and `item` Object Validation

`metadata` Object

Sample Request

Sample Response

Understanding API Responses

Errors

Overview

Base URL

Region

Headers

HTTP Method

Query Parameters

📘Identity Not Passed

Body Parameters

coupon Object

📘Coupon ID and Coupon Code Handling

order Object

item Object

📘order and item Object Validation

metadata Object

Sample Request

Sample Response

Understanding API Responses

Errors

📘
Identity Not Passed

`coupon` Object

📘
Coupon ID and Coupon Code Handling

`order` Object

`item` Object

📘
`order` and `item` Object Validation

`metadata` Object