Allows redeeming active points of customers according to the redemption criteria set for the organization (Loyalty Program). For example, you could set redemption criteria as allow redemption only in multiples of 10 and a maximum of 200 points per time.

This API checks if a specific number of points can be redeemed by a customer from a selected loyalty program. The eligibility check uses only the points balance in the selected program, not the total points across all programs. If a customer has points in other programs, those balances are not considered for this check. Store-to-program mapping determines which program's balance is checked for redemption eligibility. For example, the mapping between a store and a program (such as uat.promised.points to ROOT concept) controls which program's points are used for the redemption request.

With this API, you can now issue a validation code to the customer automatically upon successful validation. This reduces the need to call the /points/validationcode API separately.

📘
If there is any problem in issuing validation code, Points Redeemable but OTP Generation failed error will be displayed (876) * if points validation itself fails, then the relevant error message will be displayed

Example request

curl --location 'https://eu.api.capillarytech.com/v1.1/points/isredeemable?mobile=9777785205&program_id=973&format=json&points=10&issue_otp=null&validation_code=true' \
--header 'Authorization: Basic bWFkaHVMjU2YQ==' \
--header 'Cookie: _cfuvid=7165ECtxDm51hFGZ_zSJYF7reiBXgk4OldF_d7_82Iw-1761202117837-0.0.1.1-604800000'

Prerequisites

Basic Authentication
Default access group

Resource information

URI	/v1.1/points/isredeemable?
HTTP method	GET
Authentication	Basic
Pagination supported?	NO
Rate limit	YES. Demo and testing clusters: 1000 requests per minute per API key. Other organizations: Rate limit is brand-specific.
Batch support	NO

Request Parameters

Parameter (Parameters marked in * are mandatory)	Type	Description
mobile/email/external_id/card_number/card_external_id*	Enum	Pass any of the registered identifier type.
program_id*	long	Unique ID of the loyalty program from which points need to redeem.
group_redemption	boolean	Pass `true` for group redemption - points earned in one program need to redeem in a different program of the org.
points*	int	Number of points to redeem.
issue_otp	boolean	Pass `true` to issue OTP if the validation is successful.
validation_code	string	OTP issued to the customer’s mobile number.
skip_validation	boolean	Pass `true` if you want to skip validation.
validation_type	Enum	Preferred mode of validation. Value: `MISSED_CALL`, `SMS`, `INVALID`. Use invalid if you want to skip_validation.
user_group2_primary_user_id	long	Unique user ID of the primary member of the group associated with the points to redeem.
user_group2_id	int	Unique ID of the group associated with the points to redeem.
user_group2_primary_user_source	Enum	Source in which the primary user’s identifier is available. Value: `FACEBOOK`, `WEB_ENGAGE`, `WECHAT`, `INSTORE`, `MARTJACK`, `TMALL`, `TAOBAO`, `JD`, `ECOMMERCE`, `WEBSITE`, `LINE`, `MOBILE_APP`.
user_group2_primary_user_accountId	string	Account ID of the source with multiple accounts such as WECHAT.
user_group2_primary_user_identifier_type	Enum	Identifier type used for the primary member. Value: `mobile`, `email`, `cardnumber`, `cardExternalId`, `id`.
user_group2_primary_user_identifier_value	string	Value of the specified identifier type.
user_group2_external_id	string	Unique external ID of the group associated with the points to redeem.
use_default_user_group2	boolean	Pass `true` to associate the default group with the points to redeem.
currency_input	boolean	Pass `true` whether the points of worth n can be redeemed. For example, you can check if points of worth $5 can be redeemed (assuming $ as the base currency). To use this, ensure that the org currency ratio is configured for the org.

Example response

{
    "response": {
        "status": {
            "success": "true",
            "code": 200,
            "message": "Success"
        },
        "points": {
            "redeemable": {
                "mobile": "919777785205",
                "email": "testgrp3@gmail.com",
                "external_id": "434547",
                "points": 10,
                "is_redeemable": "true",
                "points_redeem_value": 10,
                "points_redeem_local_value": 10,
                "input_type": "points",
                "points_currency_ratio": "1",
                "item_status": {
                    "success": "true",
                    "code": 800,
                    "message": "Points can be redeemed"
                }
            }
        }
    }
}

Response parameter

Parameter Path	Type	Description
response	boolean	true if the request succeeded.
status	integer	HTTP status code (e.g., 200 for success).
-message	string	Human-readable status message (e.g., "Success").
mobile	string	Customer’s registered mobile number (masked or full, based on configuration).
email	string	Customer’s registered email address.
externalId	string	Customer’s external identifier
points	integer	Points requested for redemption.
-is_redeemable	boolean	true if points are redeemable.
-points_redeem_value	decimal	Equivalent monetary value of redeemable points
-points_redeem_local_value	decimal	Equivalent monetary value in local currency (if conversion is enabled).
-input_type	string	Type of input (e.g., "points" or "currency").
points_currency_ratio	string	Conversion ratio between points and currency (e.g., "1").
-item_status	boolean	true if points validation passed.
--code	integer	Sub-status code for redemption checks (e.g., 800).
--message	string	Detailed message (e.g., "Points can be redeemed").

API specific error codes

Error Code	Description	Reason
889	Points processing failed, Please try again later Reason : Failed to Connect to Service	Invalid Customer identifiers passed
1101	invalid programId passed	Invalid `programId` passed
801	Trying to redeem invalid points	Invalid `points` parameter passed (e.g, negative points value)
818	Current points are less than points requested for redemption	The customer's points balance in the selected program is less than the requested redemption amount. Only the balance in the selected program is checked, even if the customer has points in other programs. Store-to-program mapping determines which program's balance is used for this check.