Evaluate Cart Promotions

post

https://{host}/v1/promotions/evaluate

The Evaluate Promotions API returns the list of promotions applicable to a transaction by evaluating the current cart and customer data.

📘
Note

When there are multiple items with the same SKU, each item is evaluated individually, and the discount is split based on quantity or value. For example: If you add two Coke bottles to the cart twice(two SKU's), and there's an offer of ₹10 off on a combo of two bottles, the discount remains ₹10. It is split equally — ₹5 for each combo.

Cart locking functionality during cart evaluation, which temporarily reserves the applied promotion exclusively for the customer, is disabled by default. To enable it, you must raise a support ticket with capillary to activate the isLockingEnabled configuration for the particular org.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/evaluate' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-AUTH-ORG-ID: 1007373' \
--header 'Authorization: Basic bmFtYW5fZG9jOmYjgyMzA3MWJmYjM5OGM5ZmM2YjZlY2I2MmEy' \
--header 'Cookie: _cfuvid=e_HL.m0dlBkoVzuS7spjZIGUb_7oNlVY2NBLi_LRMkg-1743071078145-0.0.1.1-604800000; _cfuvid=FJOLk_InVldNoSbYZk.nP2jNZssRgKvrDSafX7f9Nrc-1743426884062-0.0.1.1-604800000' \
--data '{
    "amount": "2000.00",
    "customerId": 98662653,
    "cartItems": [
        {
            "sku": "Sku#Fuel",
            "amount": "1000.00",
            "qty": "1.000000",
            "discount": null,
            "categoryList": [
                "Fuel",
                "Premium"
            ],
            "brandList": [
                "MaxFuel",
                "FuelCo"
            ]
        },
        {
            "sku": "Sku#food",
            "amount": "1000.00",
            "qty": "1.00",
            "discount": null
        }
    ],
    "promoCodes": null,
    "paymentVouchers": null,
    "cartTenders": [
        {
            "identifier": "CreditCard",
            "amount": "500.00"
        }
    ],
    "categoryHierarchySentInPayload": true
}'

Headers

Header Name	Type	Description
`X-CAP-API-ATTRIBUTION-TILL-CODE`	`string`	This header maps the provided till code to its corresponding till identifier. The API uses this identifier to fetch the correct organizational hierarchy and return only those cart promotions applicable to the transactions at that specific till and its associated store hierarchy.

Request Body

Field	Type	Required	Description
amount	BigDecimal	Yes	Total value of the products in the cart.
customerId	Long	Yes	Unique ID of the customer.
cartItems	Array	Yes	List of objects containing details of the products in the cart.
.sku	String	Yes	Unique identifier (SKU) for the product.
.amount	BigDecimal	Yes	Price of the product.
.qty	BigDecimal	Yes	Total quantity of the product.
.discount	BigDecimal	Optional	Discount applied to the item, if any.
.categoryList	Array	Optional	Categories the product belongs to. For example, `["Fuel", "Premium"]`.
.brandList	Array	Optional	Brands associated with the product. For example, `["MaxFuel", "FuelCo"]`.
cartTenders	Array	Optional	List of objects containing details of the payment method used for purchase.
.identifier	String	Yes	Identifier of the payment method used for the purchase.
.amount	BigDecimal	Yes	Total amount paid using the payment method.
promoCodes	Array	Optional	List of promotion codes to apply to the cart.

Example response

{
    "data": {
        "amount": "2000.000000",
        "customerId": 98662653,
        "cartItems": [
            {
                "referenceId": "f297716f-c3ee-4936-b88e-a5e0ed91d262",
                "sku": "Sku#food",
                "amount": "1000.000000",
                "qty": "1.000000",
                "discount": "0",
                "appliedPromotions": []
            },
            {
                "referenceId": "20f142ec-9a10-49f6-a326-abc48f58d904",
                "sku": "Sku#Fuel",
                "amount": "1000.000000",
                "qty": "1.000000",
                "discount": "0",
                "appliedPromotions": []
            }
        ],
        "evaluationId": "67ea9543e1c34e7d8e936839",
        "appliedPromotions": [
            {
                "promotionId": "67dd2a7cef21a64211227d02",
                "name": "promotion-cart",
                "messageLabel": "test!!",
                "promotionMode": "DISCOUNT",
                "redemptionCount": 1,
                "discount": "100.000000",
                "identifier": "eyJwcm9tb3Rpb25JZCI6IjY3ZGQyYTdjZWYyMWE2NDIxMTIyN2QwMiIsImRpc2NvdW50IjoiMTAwLjAwMDAwMCIsImFtb3VudCI6IjIwMDAuMDAwMDAwIiwicmVkZW1wdGlvbkNvdW50IjoxLCJ2ZXJzaW9uIjoidjEifQ=="
            }
        ],
        "appliedPaymentVouchers": [],
        "promoCodeEvaluationLogs": [],
        "paymentVoucherEvaluationLogs": [],
        "cartTenders": [
            {
                "identifier": "CreditCard",
                "amount": "500.00",
                "referenceId": "67ea9543e1c34e7d8e936831",
                "adjustedAmount": "500.00"
            },
            {
                "identifier": "CASH",
                "amount": "1400.000000",
                "referenceId": "67ea9543e1c34e7d8e936836",
                "adjustedAmount": "1400.000000"
            }
        ],
        "categoryHierarchySentInPayload": false
    }
}

Response parameters

Field	Description
amount	Total value of the products in the cart.
customerId	Unique ID of the customer.
evaluationId	Unique identifier generated for this specific evaluation of the cart.
.cartItems	Object containing details of the products in the cart
..referenceId	Unique identifier for the cart item.
..sku	Unique identifier (SKU) for the product.
..amount	Price of the product.
..qty	Total quantity of the product
..discount	Discount applied to the item, if any.
appliedPromotions	Object containing details of cart promotions applied to this cart.
..promotionId	Unique ID of the cart promotion.
..name	Unique name of the cart promotion.
..messageLabel	Unique message is displayed to the end user to describe the promotion.
..promotionMode	Type of cart promotion. Possible values: `DISCOUNT`: Promotion is a standard discount promotion. `PAYMENT_VOUCHER`: Promotion includes a payment voucher promotion.
..redemptionCount	Total number of times the cart promotion is redeemed.
..discount	Total discount applied to the cart.
..identifier	Base64 encoded details of the applied cart promotion. You can use this when redeeming a cart promotion using the add transaction API.
appliedPaymentVouchers	Payment vouchers applied, if any.
.cartTenders	Object contains details of the payment methods used for the purchase.
..identifier	Identifier of the payment method used for the purchase.
..amount	Total amount paid using the payment method.
..referenceId	Unique ID for the cart tender.
..adjustedAmount	Total amount paid using the payment method.
categoryHierarchySentInPayload	Indicates whether the product category hierarchy was included in the request.

Error codes

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters are provided and valid.
404	Promotion or customer not found. Use valid and existing promotion and customer identifiers.
701	Error while calling segmentation engine. Check segmentation engine service connectivity and logs.
702	Error while getting org entities. Confirm org entities and service health.
703	Org timezone fetch failed. Verify org timezone configuration and service availability.
704	Invalid reward type passed. Provide a valid reward type as per API specification.
707	The passed promotion type is not supported. Change the promotion type to one supported by the system.
1006	Invalid customer identifier. Provide a valid customer identifier.
1007	Error while fetching customer identifier. Retry after checking the customer details and service status.
500	Internal server error. Retry the request after a short delay, and contact support if the error persists.

Language

Credentials

Basic

base64

URL

Click Try It! to start a request and see the response here!