Redeem Points

post https://{host}/v1.1/points/redeem

This API enables you to redeem points of a customer.

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

Example request

curl --location 'https://eu.api.capillarytech.com/v1.1/points/redeem?skip_validation=false&program_id=973&format=json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWFkaH3MjU2YQ==' \
--header 'Cookie: _cfuvid=XumIPWGQWMR5H_KoNPj_nCPZxmHNpwo5t.jJOsDKIDg-1760604030972-0.0.1.1-604800000' \
--data '{
    "root": {
        "redeem": [
            {
                "points_redeemed": 1,
                "customer": {
                    "mobile": "919777788221"
                },
               "transaction_number": "bilnum100000", 
                "notes": "Redeemed to transfer points to the friend",
                "validation_code": "NS3U05", 
                "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
Rate limit	Demo and testing clusters: 1000 requests per minute per API key. Other organizations: Rate limit is brand-specific.
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
`transaction_number`	String	Unique identifier for the transaction.
`customer`	Object	An object containing information about the customer involved in the transaction
`mobile*`	String	The mobile phone number of the customer
`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.

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": "[email protected]",
                "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.
`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.

Api Specific Error Code

Error Code	Description	Reason
801	Trying to redeem invalid points	The value provided for `points_redeemed` is invalid (for example, a negative number). 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.

Language

Credentials

Basic

base64

URL

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