Update redeem points

put https://{host}/v2/points/updateRedemption

This API allows you to add or update metadata for a point redemption. The following fields can be edited:

bill_id
bill_number
purpose
custom fields

👍
Note
For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

Example request

curl --location --request PUT 'https://eu.api.capillarytech.com/v2/points/updateRedemption' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic bWFkaHzI3MjU2YQ==' \
--header 'Cookie: CC=hxVc6LZCMF1eeNlIK-5ArYCe6cvhui9bPBrNvPuITC4sjNGnu38i6U7XPncmwdOS; CT=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6WyIxNDgzNTYiXSwib3JnSUQiOjUwMzY2LCJleHAiOjE3MjIwNTc1NzEsImlhdCI6MTcyMTk3MTE3MiwiaXNzIjoiY2FwaWxsYXJ5dGVjaC5jb20iLCJhdWQiOiJjYXBpbGxhcnksaW50b3VjaCxhcnlhLHJlb24sYXBwcyIsInNvdXJjZSI6IldFQkFQUCJ9.QOKPoNaoFROpdU6hqQHtJnV1HmlYPDu8QRZHUsZxiX0; OID=50366; _cfuvid=v4REFESfdMALppPg_TcpQuUBTBwlGF7_qbRvsCR1zTM-1761219794658-0.0.1.1-604800000' \
--data '{
    "redemptionId": "NZVAt9", 
    
    "billNumber": "billnumber333",
    "billId": 12345678901, 
    "purpose": "testing123",
    "entity": {
        "type": "CUSTOMER",
        "identifierType": "mobile",
        "identifierValue": "919777785302"
    }
}'

API specifications

Feature	Availability
Authentication supported	Basic
Pagination	Not supported
Batch support	Not supported
Access Group	Yes

Request parameters

{
    "redemptionId": "Fnpztw",
    "billNumber": "txn-79",
    "purpose": "Update redemption details",
    "entity": {
        "type": "CUSTOMER",
        "identifierType": "mobile",
        "identifierValue": "919731013853"
    },
    "customFields": {
        "card_number": "123456"
    }
}

Request body parameters

Parameter	Data Type	Description
redemptionId*	String	A unique identifier for the redemption process. The `redemptionId` is generated when redeeming points using the redeem points API.
billNumber	String	A string identifier for the bill.
billId	Integer	A numerical identifier for the bill. The maximum number of supported characters is 19. Must be a positive whole number without decimals or special characters. For example: Valid billId: 1234567890123456789 Invalid billId: "12345.67", "ABC123", "-12345"
purpose	String	The purpose or reason for the redemption update. The maximum character limit is 255 characters.
entity	Object	An object containing details about the entity.
type*	Enum	The type of entity involved in the transaction. Supported values: `CUSTOMER`, `USERGROUP2`, `FLEET`
identifierType*	Enum	The type of identifier used for the entity.
identifierValue*	String	The value of the identifier for the entity.
customFields	Object	Object containing details of custom fields for the point redemption.
key `<value>`	String	Key-value pairs of the custom field and their respective values. Notes: Before using custom fields, ensure they are created in the organisation. For more information on creating custom fields, refer to the section on creating a new custom field. You can add or edit custom fields only if you include custom field metadata during the points redemption event. Include the custom fields when redeeming points using the Redeem points API.

Note: It is mandatory to pass either redemptionId or externalReferenceNumber.

Response body

{
    "id": 26445488,
    "programId": 973,
    "pointsRedeemed": 1.0,
    "billId": 12345678901,
    "billNumber": "billnumber333",
    "validationCode": "NS3U05",
    "notes": "Redeemed to transfer points to the friend",
    "redemptionTime": 1749721256000,
    "pointsRedemptionTime": 1749701456000,
    "tillId": 75155295,
    "tillName": "",
    "pointDeductionList": [],
    "redemptionId": "NZVAt9",
    "customerId": 564670755,
    "redemptionPurpose": "testing123",
    "redemptionDate": "2025-06-12T09:40:56Z",
    "warnings": []
}

{
    "id": 26503632,
    "programId": 973,
    "pointsRedeemed": 101.0,
    "billId": -1,
    "billNumber": "txn-79",
    "validationCode": "NS3U05",
    "notes": "Redeemed to transfer points to the friend",
    "redemptionTime": 1750951708000,
    "pointsRedemptionTime": 1750931908000,
    "tillId": 75152721,
    "tillName": "",
    "pointDeductionList": [],
    "redemptionId": "Fnpztw",
    "customFields": [
        {
            "name": "card_number",
            "value": "123456"
        }
    ],
    "customerId": 564332013,
    "redemptionPurpose": "testUpdate",
    "redemptionDate": "2025-06-26T15:28:28Z",
    "warnings": []
}

Response body parameters

Key	Data Type	Description
id	Long	Unique ID of the customer.
programId	Integer	Unique ID of the loyalty program.
pointsRedeemed	String	Number of points redeemed during the redemption.
billId	Long	Unique ID generated after a transaction. The maximum number of supported characters is 19. It must be a positive whole number, without decimals or special characters. For example: Valid billId: 1234567890123456789 Invalid billId: "12345.67", "ABC123", "-12345".
billNumber	String	Unique ID associated with the transaction. This is provided when adding a transaction.
validationCode	String	Unique code to validate the redemption.
notes	String	Notes related to the redemption update, if any.
redemptionTime	Date	Timestamp when the redemption event was initiated or performed
pointsRedemptionTime	Date	Timestamp when the points were deducted from the warehouse or backend system.
tillId	Integer	Till ID from where the redemption occurred.
tillName	String	Name of the till where the redemption occurred.
pointDeductionList	Object	Object containing details of the point deduction.
redemptionId	String	Unique ID of the redemption event.
customFields	Object	Object containing details of custom fields associated with the points redemption.
customFields.name	String	Name of the custom field.
customFields.value	String	Value of the custom field.
customerId	Integer	Unique customer identifier whose points were deducted.
redemptionPurpose	String	Purpose for updating the points redemption details.
redemptionDate	Date	Date when the redemption occurred in ISO 8601 format.
warnings	Object	Object containing warnings that occured, if any.

API-specific error codes

Error Code	Description	Reason / When It Occurs
748	No metadata update requested.	The request did not include any updatable fields (e.g., no new bill number, bill ID, or purpose provided).
749	Exactly one redemption identifier needed to identify redemption.	You must pass only one valid identifier (`redemptionId`, `billNumber`, or another allowed ID). Passing none or multiple identifiers triggers this error.
750	Redemption update failed: 0.	The update action failed internally, possibly due to invalid status transitions or data integrity issues. `{0}` provides specific details.
1219	Entity details not set/invalid.	The `entity` object is missing or its fields (`type`, `identifierType`, `identifierValue`) are incomplete or invalid.
1212	Entity type passed is not valid.	The `entity.type` value (e.g., `CUSTOMER`, `groupUser`) is incorrect or not supported for your configuration.
8015	Invalid or malformed identifier provided in request body.	The `identifierValue` or `redemptionId` is missing, incorrectly formatted, or does not exist in the system.

Language

Credentials

Basic

base64

URL

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