❗️
Make sure you have the appropriate access control configured. For more information, see access group documentation.

Example request

curl -L 'https://eu.api.capillarytech.com/v1.1/points/redeem?skip_validation=false&program_id=973&format=json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic 5ZmM2YjZlY2I2MmEy' \
-H 'Cookie: _cfuvid=XumIPWGQWMR5H_KoNPj_nCPZxmHNpwo5t.jJOsDKIDg-1760604030972-0.0.1.1-604800000; _cfuvid=Oh0QQggV8MSU5DNV505fn9BgzCqkOeV.cY67BUlO6oM-1762510017386-0.0.1.1-604800000' \
-d '{
    "root": {
        "redeem": [
            {
                "points_redeemed": 1,
                "customer": {
                    "mobile": "919988776655"
                },
               "external_reference_number":"a3fd1a63-1aa3-4c47-9173-398",
               "transaction_number": "bilnum100000", 
                "notes": "Redeemed to transfer points to the friend",
               
                "custom_fields": {
                    "field": [
                        {
                            "name": "point_transfered_to",
                            "value": "9777788221"
                        }
                    ]
                }
            }
        ]
    }
}'

Prerequisites

Basic Authentication
Default access group

Resource information

URI	/v1.1/points/redeem
HTTP method	POST
Authentication	Basic
Pagination supported?	NO
Batch support	NO

📘
Notes
If you are using validation code, make sure to use it within the validity period.

You can check the validity set for the validation code in OTP code validity period field on InTouch > Settings > Organization Setup > OTPConfigurations page.

Body parameters

Parameter	Data Type	Description
redeem	Array	An array containing objects representing individual redemption transactions
.points_redeemed	Integer	The number of points that were redeemed in the transaction
..customer	Object	An object containing information about the customer involved in the transaction
...mobile*	String	The mobile phone number of the customer
.transaction_number	String	Unique identifier for the transaction.
.external_reference_number	String	A plain string reference identifier for the points redemption attempt. Each `external_reference_number` must be unique for a redemption. This is used for an idempotency check. There is no character limit for this parameter.
.notes	String	Notes or additional information about the transaction
.validation_code	String	Validation code for the transaction.
.custom_fields	Object	Organization-specific custom fields. The custom field must exist in the organization.
..field	Object	Object containing the key-value pairs for the custom field.
...name	String	Key of the custom field. For example, if the custom field is "redemption_channel", provide the same.
...value	String	Value for the provided custom field `name`. For example, if the custom field is "redemption_channel", provide a valid enum for the field such as `App`, `Website`, `In-store`, `POS`.

Query parameters

Parameter	Data Type	Description
`user_group2_primary_user_id`	String	Unique user ID of the primary member of the group associated with the points to redeem.
`user_group2_id`	String	Unique ID of the group associated with the points to redeem.
`user_group2_external_id`	String	Unique external ID of the group associated with the points to redeem.
`user_group2_primary_user_source`	String	Source in which the primary user’s identifier is available. Allowed values: `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`	String	Identifier type used for the primary member. Allowed values: `mobile`, `email`, `cardnumber`, `cardExternalId`, `id`.
`user_group2_primary_user_identifier_value`	String	Value of the specified identifier type.
`skip_validation`	Boolean	Pass `true` to skip customer validation to redeem points.
`program_id`	String	Unique ID of the program from which points need to be redeemed. Applicable for orgs with multi-loyalty program enabled.
`validation_type`	String	Validation type used to redeem points. Allowed values: `MISSED_CALL`, `SMS`.

❗️
Note
You must provide at least one of the parameters marked with ** for group level points redemption.

Example response

{
    "response": {
        "status": {
            "success": "true",
            "code": 200,
            "message": "Success"
        },
        "responses": {
            "points": {
                "mobile": "919777788221",
                "email": "tomswayer@gmail.com",
                "external_id": "123456",
                "user_id": "564670755",
                "redemption_id": "7t4y2a",
                "points_redeemed": "1",
                "redemption_purpose": "",
                "redeemed_value": 1,
                "redeemed_local_value": 1,
                "balance": 1990,
                "side_effects": {
                    "effect": [
                        {
                            "id": 27141811,
                            "case_value": "false",
                            "num_points": 1,
                            "currency_value": 1,
                            "validation_code": "NS3U05",
                            "points_redemption_summary_id": "27141811",
                            "redeemed_on_bill_number": "bilnum100000",
                            "redeemed_on_bill_id": -1,
                            "type": "points"
                        }
                    ]
                },
                "item_status": {
                    "success": "true",
                    "code": 800,
                    "message": "Points Redeemed"
                }
            }
        }
    }
}

Response parameter

Parameter	Data Type	Description
`response`	Object	The root object that contains all the details of the response.
`status`	Object	An object containing the status details of the response.
`success`	String	A string indicating the success status of the response.
`code`	Integer	The HTTP status code associated with the response.
`message`	String	A general message providing additional information about the status of the response.
`responses`	Object	An object containing detailed response data.
`points`	Object	An object containing detailed information about the points involved in the transaction.
`mobile`	String	The mobile phone number associated with the account involved in the transaction.
`email`	String	The email address associated with the account involved in the transaction.
`external_id`	String	An external identifier for the transaction.
`user_id`	String	The user ID associated with the account involved in the transaction.
`redemption_id`	String	A unique identifier for the redemption transaction.
`points_redeemed`	String	The number of points that were redeemed in the transaction.
`redemption_purpose`	String	The purpose of the redemption.
`redeemed_value`	Integer	The value of the points that were redeemed.
`redeemed_local_value`	Integer	The local value of the points that were redeemed.
`balance`	Integer	The remaining balance of points in the account after the redemption.
`side_effects`	Object	An object containing information about any side effects of the redemption.
`effect`	Array of Objects	An array containing objects representing individual effects of the redemption.
`id`	Integer	A unique identifier for an individual effect.
`case_value`	String	A string indicating whether a certain case is true for the effect. If your loyalty program doesn't have tracker cases configured for redemptions, the Points Engine returns "false" to indicate: No case matching was performed Tracker-based redemption rules are not active Standard redemption rules were applied
`num_points`	Number	The number of points involved in the effect.
`currency_value`	Integer	The currency value associated with the effect.
`validation_code`	String	A validation code associated with the effect.
`points_redemption_summary_id`	String	A summary ID associated with the points redemption.
`redeemed_on_bill_number`	String	The bill number associated with the redemption.
`redeemed_on_bill_id`	Integer	The bill ID associated with the redemption.
`type`	String	The type of effect.
`item_status`	Object	An object containing the status details of the item in the response.
`code`	Integer	The HTTP status code associated with the item status (800 indicates points were redeemed).
`message`	String	A general message providing additional information about the status of the item in the response.

Error code

Error Code

Description

3316 - group redemption action executed from non group redemption payload

Create a JIRA ticket to the Product Support team and disable the configuration ENABLE_GROUP_PROGRAMS_REDEMPTION.

521

The system is processing another request for the same customer. A customer-level lock is held for the duration of each request. If a second request for the same customer arrives before the first completes, the system cannot acquire the lock and rejects the request with 521. This is expected behavior. Retry the failed request after a short delay. To avoid elevated 521 rates in bulk flows, send requests for the same customer sequentially and implement a retry with backoff.

Api Specific Error Code

Error Code	Description	Reason
801	Trying to redeem invalid points	The system validates if points value is strictly greater than 0. Any value that is null, 0, or negative is treated as invalid and will result in an error code. Provide a valid value for `points_redeemed` parameter.
878	Invalid decimal precision in points redeemed	This error occurs when the points redeemed field contains a value with more than three decimal places (e.g., "1.1111" or "10.12345"). The API expects this field to have a maximum of three decimal places. If this precision is exceeded, error 878 is returned.
1632	Invalid or non-existent groupId	The groupId provided is missing, invalid, or does not exist.
828	Points redemption not configured for the group	The group does not have points redemption set up in the system.

200200

400400