Overview

The Validate Coupon API enables you to verify the validity and applicability of a coupon code entered by users at checkout. Verifying coupon details against 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 to 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

The following is a sample base URL:

https://<region>.api.clevertap.com/1/promo/coupons/validate

For region-specific endpoints, refer to Region.

HTTP Method

POST

Headers

For more information about API headers, refer to Headers.

Query Parameters

The following table lists the query parameters.

Body Parameters

The body parameters define the structure and data required for coupon validation. The request body accepts a top-level couponCode field and an order object. The items array is nested inside the order object.

The following table lists the top-level body parameters.

order Object

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

The following table lists the order object parameters.

items Array (nested inside order)

The items array is nested inside the order object and provides details about individual items in the cart. If the items array 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.

The following table lists the items object parameters.

metadata Object

The metadata object allows you to include additional custom key-value pairs for advanced coupon validations. It can be passed within both the order and items objects.

The following table lists the metadata object parameters.

Example Request

The following is a sample request to the Validate Coupon API, showing the headers needed to authenticate the request.

curl -X POST "https://<region>.api.clevertap.com/1/promo/coupons/validate?identity=krishna123" \
-H "X-CleverTap-Account-Id: ACCOUNT_ID" \
-H "X-CleverTap-Passcode: PASSCODE" \
-H "Content-Type: application/json" \
-d '{
    "couponCode": "FLAT500",
    "order": {
        "orderId": "order12345",
        "saleMrpTotal": 399,
        "saleAmount": 101,
        "saleChannel": "online",
        "location": "BLR",
        "locationId": "IND",
        "orderStatus": "pending",
        "items": [
            {
                "productId": "123456",
                "sku": "124",
                "itemName": "Cotton Shirt",
                "category": "shirts",
                "subCategory": "cotton shirts",
                "brand": "superdry",
                "unitPrice": 300,
                "mrp": 300,
                "quantity": 3,
                "metadata": {
                    "color": "blue"
                }
            },
            {
                "productId": "123457",
                "sku": "125",
                "itemName": "Chino Trouser",
                "category": "trousers",
                "subCategory": "",
                "brand": "levis",
                "unitPrice": 100,
                "mrp": 100,
                "quantity": 1,
                "metadata": {
                    "color": "khaki"
                }
            }
        ],
        "metadata": {
            "customerType": "guests"
        }
    }
}'

Find CleverTap Account ID and Passcode

You can find the CleverTap Account ID and Passcode from the CleverTap dashboard by navigating to Settings > Project.

Example Response

The following is a sample response.

{
    "status": "success",
    "records": [
        {
            "couponTimeframe": [
                {
                    "timeSlot": {
                        "startTime": "00:00AM",
                        "endTime": "11:59PM"
                    },
                    "validationDay": "All"
                }
            ],
            "couponName": "FLAT500",
            "couponExpiry": 32494151843,
            "couponCodeId": 1003,
            "totalRedemptionUnlimited": true,
            "isApplicable": true,
            "description": "This offer is applicable on order above $100",
            "message": "",
            "couponExpiryNever": true,
            "termsAndConditions": [
                "Applicable on order above $100",
                "Valid till may end"
            ],
            "discountEffect": {
                "discountRate": 100,
                "rewardType": "discount",
                "discountType": "entireOrder",
                "discountAppliedOn": "saleAmount",
                "discountValue": "absolute"
            },
            "totalRedemptionLeft": 0,
            "couponSavings": { "...": "..." },
            "bestCoupon": "",
            "identity": "j541399",
            "requestId": "",
            "redemptionActivationDate": 1755446400,
            "userRedemptionUnlimited": false,
            "redemptionStatus": true,
            "couponCode": "FLAT500",
            "userRedemptionLeft": 1
        }
    ]
}

The response structure is the same as the Fetch Coupon API response. The following difference applies to the validate endpoint: the bestCoupon field returns an empty string ("") in the validate response, rather than "Yes" or "No". This is because the best-coupon ranking is not computed during single-coupon validation.

Understanding API Responses

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

Errors

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