Time	Status	User Agent
Retrieving recent requests…

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

📘
Note
For the v2 equivalent of this API, see Redeem customer points (POST /v2/customers/{id}/redemptions).

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' \
-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

📘
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": "[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": {
        "status": {
            "success": "true",
            "code": 200,
            "message": "Success"
        },
        "responses": {
            "points": {
                "mobile": "919998872203",
                "email": "[email protected]",
                "external_id": "",
                "user_id": "568376576",
                "redemption_id": "uN1oA9",
                "points_redeemed": "10",
                "redemption_purpose": "",
                "redeemed_value": 10,
                "redeemed_local_value": 10,
                "balance": 10000,
                "is_group_redemption": true,
                "side_effects": {
                    "effect": [
                        {
                            "id": 28453291,
                            "case_value": "false",
                            "num_points": 10,
                            "currency_value": 10,
                            "validation_code": "",
                            "points_redemption_summary_id": "28453291",
                            "redeemed_on_bill_number": "txn-166",
                            "redeemed_on_bill_id": -1,
                            "type": "points"
                        }
                    ]
                },
                "item_status": {
                    "success": "true",
                    "code": 800,
                    "message": "Points Redeemed"
                }
            }
        }
    }
}

Response parameters

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.
`...is_group_redemption`	Boolean	`true` when the redemption was processed as a cross-member First Expiry, First Out (FEFO) redemption. Present only when `ENABLE_CROSS_MEMBER_REDEMPTION` is enabled for the org and the transacting customer is an active member of a UserGroup2 group. Not present for standard individual or UserGroup2 group redemptions using `user_group2_*` params.
`...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, and 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 & warning codes

Code	Error number	Type	Description
—	521	Error	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.
—	3316	Error	Group redemption action executed from a non-group redemption payload. Raise a JIRA ticket to the Capillary product support team and disable the configuration `ENABLE_GROUP_PROGRAMS_REDEMPTION`.
—	801	Error	Trying to redeem invalid points. The system validates that `points_redeemed` is strictly greater than 0. Any value that is null, 0, or negative is treated as invalid. Provide a valid value for `points_redeemed`.
—	828	Error	Points redemption not configured for the group. The group does not have points redemption set up in the system.
—	878	Error	Invalid decimal precision in points redeemed. The `points_redeemed` field must have a maximum of three decimal places. For example, `1.1111` or `10.12345` would trigger this error.
—	1632	Error	Invalid or non-existent groupId. The groupId provided is missing, invalid, or does not exist.

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

Note

Example request

Prerequisites

Notes

Body parameters

Query parameters

Note

Example response

Response parameters

Error & warning codes

200200

400400