Overview

The Points Validation API enables you to verify whether a user's loyalty points redemption is allowed for a given cart and calculate the points discount based on the configured points ratio. Validating the redemption against the wallet's configured rules ensures accurate discounts without building the validation logic in your application.

The API evaluates the redemption rule configured in the loyalty wallet, applies the applicable points-to-currency ratio, calculates the discount amount, and returns a single result per call. You can integrate this API at relevant touchpoints within the application or website.

This API validates and calculates only. It does not move points. To deduct points from the wallet ledger, call the Debit/Credit Wallet API separately with the pointsToDebit value returned in the response.

You can use this API in the following cases:

• When the user enters the number of points to redeem at checkout.
• When the user modifies the cart after entering the points to redeem.
• When you need the points discount for the entered points, before debiting them.
• At any other custom checkpoint in the user journey where points redemption validation is required, such as a cart review step, a payment-options screen, or a final order-confirmation step, before the Debit call.

Prerequisites

Before you call this API, ensure the following:

• A redemption rule is saved on the loyalty wallet. Wallets created before this feature have no rule by default. Save one from the wallet edit flow, or the request fails.
• Any cart or product property referenced by the wallet's rules is included in the request payload.

Base URL

The following is a sample base URL for the account in the India region:

https://in1.api.clevertap.com/1/promo/wallets/points/validate?walletId=5167&identity=User1

For region-specific endpoints, refer to Region.

HTTP Method

POST

Headers

For more information about API headers, refer to Headers.

Path Parameters

The following table lists the path parameters:

Body Parameters

The request body accepts a pointsRequested 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 redemption effectively, as qualification and discount calculations depend on these order details.

The following table lists the order object parameters:

items Array

The items array is nested inside the order object and provides details about individual items in the cart. The entire array is optional. An individual key becomes mandatory only when the product qualification rule or a product-based ratio override of the wallet is configured on that key. The API evaluates those rules against each item in the array.

The following table lists the items object parameters:

metadata Object

The metadata object allows you to include additional custom key-value pairs for cart and product qualification. It can be passed within both the order and items objects. The key must match the property name configured in the dashboard.

The paymentMode and cartQuantity fields are the core properties of the order object, not metadata properties.

The following table lists the metadata object parameters:

Example Request

The following is a sample request to the Points Validation API, showing the headers needed to authenticate the request:

curl --location --request POST \
'https://in1.api.clevertap.com/1/promo/wallets/points/validate?walletId=5167&identity=User1' \
--header 'X-CleverTap-Account-Id: ACCOUNT_ID' \
--header 'X-CleverTap-Passcode: PASSCODE' \
--header 'Content-Type: application/json' \
--data-raw '{
  "pointsRequested": 100,
  "order": {
    "saleAmount": 1200,
    "saleChannel": "online",
    "location": "India",
    "locationId": "IND",
    "paymentMode": "wallet",
    "cartQuantity": 3,
    "metadata": {
      "customerType": "existing"
    },
    "items": [
      {
        "productId": "abc_124",
        "sku": "124",
        "itemName": "Slim Fit Cotton Shirt",
        "category": "shirts",
        "subCategory": "cotton shirts",
        "brand": "levis",
        "unitPrice": 400,
        "mrp": 400,
        "quantity": 3,
        "metadata": {
          "fabric": "cotton"
        }
      }
    ]
  }
}'

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

Example Response

The API returns two different response shapes, and the distinction affects how you parse the result.

A redemption that passes validation and a redemption rejected by a business rule both return status as success in the same envelope. A business rule rejection returns isApplicable as false with a code and message, and includes requestId.

Redemption Allowed

{
  "status": "success",
  "records": [
    {
      "isApplicable": true,
      "message": "",
      "pointsRequested": 100,
      "pointsToDebit": 100,
      "adjusted": false,
      "maxPointsUnlimited": true,
      "pointsDiscount": 100.00,
      "currency": "USD",
      "pointRatio": {
        "type": "default",
        "overrideName": "default",
        "value": 1
      },
      "requestId": "req_8827123"
    }
  ]
}

Redemption Rejected by Business Rule

{
  "status": "success",
  "records": [
    {
      "isApplicable": false,
      "message": "Insufficient balance, you only have 80 points available",
      "pointsRequested": 100,
      "adjusted": false,
      "pointsDiscount": 0,
      "currency": "USD",
      "pointRatio": {},
      "requestId": "req_8827124"
    }
  ]
}

Maximum Points Discount Exceeded

When the calculated discount exceeds the configured cap, the response returns both the currency cap and its points equivalent, so you do not need to reverse-calculate the redeemable points.

{
  "status": "success",
  "records": [
    {
      "isApplicable": false,
      "message": "You can redeem up to 10 points ($1.00) on this order.",
      "pointsRequested": 100,
      "maxPointsDiscount": 10,
      "maxPointsToDebit": 1.00,
      "pointsDiscount": 0,
      "currency": "USD",
      "pointRatio": {},
      "requestId": "req_8827125"
    }
  ]
}

Invalid Request

A missing or incorrectly typed parameter fails during schema validation, before any rule is evaluated. This response does not include a records array.

{
  "status": "fail",
  "error": "saleAmount is required",
  "code": 752
}

Response Parameters

Points Ratio Resolution

Overrides are checked in the rank order the marketer sets. The first override whose conditions fully match is applied, and evaluation stops there. If no override matches, the wallet's default ratio applies. An override whose key is missing from the payload simply does not match; this is not an error.

Open-ended operators can make more than one override match for the same cart. For example, cart_value >= 1000 and cart_value >= 1500 is true for a cart of 1800. Rank order decides which applies.

Discount is calculated as follows:

calculatedValue = pointsRequested x ratio.value

This value is only used for comparison. The API checks it against the cap and saleAmount before rounding, so the final discount is never derived from a rounded figure.

The API then runs the following steps in order. The order matters because the cap check and the saleAmount comparison both happen before any rounding.

1. Calculate the comparison value. Multiply the requested points by the resolved ratio. This is not the final discount.
2. Check the maximum points discount cap. For Flat and Percentage, if the comparison value exceeds the cap, the redemption is rejected with code 759, and the response returns maxPointsDiscount and maxPointsToDebit. Unlimited has no cap, so it always passes this step.
3. Compare against saleAmount. The points discount is the lower of the comparison value and saleAmount.
4. Derive the final points discount. If the comparison value is lower, round it half-up to the default decimal cap for the points discount, which is two decimal places. If saleAmount is lower, use saleAmount exactly as sent, with no rounding.
5. Reverse-calculate the points to debit. Divide the final points discount by the ratio value, then truncate to the decimal-place setting of the wallet.
6. Apply the balance safety check. If the points to debit exceed the available balance, cap them at the balance. This is a silent adjustment, not an error.

Examples

All four examples use a ratio of 0.00005 USD per point and a wallet decimal-place setting of 2.

• Points discount decimal cap: The default number of decimal places to which the calculated points discount is rounded.
• Wallet decimal-place setting: The points-precision setting of the wallet, used to truncate the points to debit (step 5).

Example 1

Rounding applied. 651,300 points requested, saleAmount 50.00, available balance 700,000, maximum points discount Unlimited.

The response returns pointsDiscount 32.57, pointsToDebit 651,400, and adjusted true. The points to be debited exceed the requested points because the discount was rounded up.

Example 2

Comparison value exceeds saleAmount. 1,200,000 points requested, saleAmount 50.00, available balance 1,200,000, maximum points discount Unlimited.

The response returns pointsDiscount 50.00, pointsToDebit 1,000,000, and adjusted true. Fewer points are debited than requested, because the discount cannot exceed the order value.

Example 3

Maximum points discount exceeded. 651,300 points requested, saleAmount 50.00, maximum points discount 20.00 Flat.

The API stops at step 2 and returns isApplicable false with code 759, maxPointsDiscount 20.00, and maxPointsToDebit 400,000. Steps 3 to 6 do not run, so no discount is calculated.

Example 4

Balance safety check applied. 651,300 points requested, saleAmount 50.00, available balance 651,350, maximum points discount Unlimited.

The response returns pointsDiscount 32.57, pointsToDebit 651,350, and adjusted true. The user receives the full discount, and the small reconciliation gap falls in the user's favor.

The cap itself is derived per unit:

Points to Debit

pointsToDebit is always reverse-calculated from the final pointsDiscount, in both the rounded and the clamped branch.

maxDecimalPlace is the wallet's points-precision setting, configured per wallet in the dashboard. It is not a request field and not a global constant.

Truncation, rather than rounding, keeps the reverse calculation from inflating the figure at the wallet's points precision. Because pointsDiscount can round up, or can equal saleAmount directly, pointsToDebit can be higher than pointsRequested. That is expected, and adjusted is returned as true.

If pointsToDebit exceeds activePoints, it is capped to activePoints and adjusted is true. This is a second balance check, the earlier check against pointsRequested is not sufficient on its own, because pointsToDebit is not known until after the calculation.

Validation Scenarios

The API validates the request in a fixed sequence and behaves in one of three ways at each step. It rejects the request, continues to the next step, or accepts the redemption with a silent adjustment. The following table lists the behavior for each case, in the sequence in which the API evaluates them.

For the message and code returned on a rejection, refer to the Errors section below.

Errors

The following table lists the errors specific to the Points Validation API:

For errors applicable to all CleverTap API requests, refer to API Error Cases.

Qualification Failure Messages

Cart and product qualification failures return one of two formats, depending on how many conditions failed.