This API updates the expiry date of points earned by a customer. It uses a customer ID and transaction reference data.

Prerequisites

Authentication: Basic/OAuth authentication
Access group: Default access group

Resource information

Property	Value
URI	/v2/points/updateExpiry
HTTP Method	POST
Pagination	Not supported
Batch support	Not supported
Rate limit information	Not Applicable

Example request

curl -L 'https://eu.api.capillarytech.com/v2/points/updateExpiry' \
-H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
-H 'X-CAP-API-AUTH: <YOUR_CAPILLARY_API_TOKEN>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "expiryDateUpdateRequest": [
        {
            "identifierName": "id",
            "identifierValue": "172440986",
            "programId": 469,
            "pointsAwardedRefId": 117521910,
            "pointsAwardedRefType": "POINT_AWARDED",
            "expiryUpdateReasonType": "EARLY_EXPIRY",
            "expiryUpdateReasonNote": "Customer made a purchase above $100",
            "standardMeta": {
                "who_raised": "Naman",
                "who_approved": "Admin",
                "reason_for_trigger": "Extend points expiry"
            },
            "customMeta": {
                "abc": "xyz"
            },
            "expiryDate": {
                "expiryType": "FIXED_DATE",
                "expiryValue": "2025-08-09"
            }
        }
    ]
}'

Request body parameters

Parameter	Data Type	Mandatory	Description
`expiryDateUpdateRequest`	object	Yes	Object containing details about the customer, the program ID, the identifiers for the points, and the metadata for the points expiration.
`identifierName`	string	Yes	Identifier type for customer ID. Supported values: `mobile`, `id`, `externalId`, `email`.
`identifierValue`	string	Yes	Value corresponding to the `identifierName` provided.
`programId`	integer (int64)	Yes	Unique ID of the loyalty program. To retrieve the `programId`, use the Get Loyalty Programs API.
`pointsAwardedRefId`	integer (int64)	Yes	Unique reference ID generated when points are awarded to a user. To retrieve the `pointsAwardedRefId`, use the Get points awarded ID API.
`pointsAwardedRefType`	enum	Yes	Type of points awarded to the user. Supported values: `POINT_AWARDED`, `POINT_AWARDED_BILL_PROMOTION`, `POINT_AWARDED_LINEITEM`, `POINT_AWARDED_LINEITEM_PROMOTION`, `POINT_AWARDED_CUSTOMER_PROMOTION`.
`currencyName`	string	No	Name of the reward currency. To retrieve the `currencyName`, refer to documentation the on Viewing alternate currencies.
`pointCategoryType`	string	No	Type of points to update the expiry. Possible values: `REGULAR`, `PROMISED`
`expiryUpdateReasonType`	enum	No	Type of expiry modification. Supported values: `EARLY_EXPIRY`, `EXTEND_EXPIRY`.
`expiryUpdateReasonNote`	string	No	Reason for updating the points expiry date.
`standardMeta`	object	No	Object containing details about the user who raised and approved the request, along with the reason for updating the expiry of points.
`who_raised`	string	No	Name or username of the user who raised the points expiry update request.
`who_approved`	string	No	Name or username of the user who approved the points expiry update request.
`reason_for_trigger`	string	No	Reason for expiring or extending the points expiry update.
`customMeta`	object	No	Object containing details of custom metadata for the points expiry update.
`expiryDate`	object	Yes	Object containing details of the updated points expiry date.
`expiryType`	enum	Yes	Type of points expiry. Supported values: `FIXED_DATE`: Points expire on a fixed date. `FIXED_DAYS`: Points expire after a fixed number of days. `FIXED_MONTHS`: Points expire after a fixed number of months. `IMMEDIATE`: Points expire immediately after the API request is executed.
`expiryValue`	string/date	Yes	The date in `YYYY-MM-DD` format or number of days after which the points expire. Timezone: Cluster-specific timezone.

Response body

{
    "currencyExpiryUpdateResponse": [
        {
            "customerId": 172440986,
            "programId": 469,
            "currencyName": "POINTS",
            "pointsExpiryUpdateLogs": {
                "paType": "POINT_AWARDED",
                "paId": 117521910,
                "expiryUpdateReasonType": "EARLY_EXPIRY",
                "expiryUpdateReasonNote": "xyz",
                "oldExpiryDate": "2026-08-09 23:59:59",
                "oldExpiryDateISO": "2026-08-09T23:59:59Z",
                "newExpiryDate": "2026-08-09 23:59:59",
                "newExpiryDateISO": "2026-08-09T23:59:59Z",
                "eventLogId": 41420339,
                "eventDate": "2026-01-07 10:35:28",
                "eventDateISO": "2026-01-07T10:35:28Z",
                "standardMeta": {
                    "reason_for_trigger": "test",
                    "who_approved": "Admin",
                    "who_raised": "Naman"
                },
                "customMeta": {
                    "abc": "xyz"
                }
            }
        }
    ]
}

{
    "currencyExpiryUpdateResponse": [],
    "failures": [
        {
            "pointsAwardedRefId": 117521910,
            "pointsAwardedRefType": "POINT_AWARDED",
            "errorCode": 8015,
            "errorMessage": "Customer not found for the given identifiers"
        }
    ]
}

{
    "currencyExpiryUpdateResponse": [],
    "failures": [
        {
            "pointsAwardedRefId": 1175219,
            "pointsAwardedRefType": "POINT_AWARDED",
            "errorCode": 3034,
            "errorMessage": "No points awarded found for reference type POINT_AWARDED and ID 1175219"
        }
    ]
}

{
    "errors": [
        {
            "status": false,
            "code": 8941,
            "message": "Valid values are: [POINT_AWARDED, POINT_AWARDED_BILL_PROMOTION, POINT_AWARDED_LINEITEM, POINT_AWARDED_LINEITEM_PROMOTION, POINT_AWARDED_CUSTOMER_PROMOTION]"
        }
    ]
}

{
    "errors": [
        {
            "status": false,
            "code": 8941,
            "message": "Valid values are: [FIXED_DATE, FIXED_DAYS, FIXED_MONTHS, IMMEDIATE]"
        }
    ]
}

{
    "currencyExpiryUpdateResponse": [],
    "failures": [
        {
            "pointsAwardedRefId": 117521910,
            "pointsAwardedRefType": "POINT_AWARDED",
            "errorCode": 3037,
            "errorMessage": "Invalid expiry date: Expiry date must be in the future"
        }
    ]
}

Response body parameters

Parameter	Data Type	Description
updateCurrencyExpiryDateResponse	Object	Object containing details of the points expiry update request.
.customerId	integer (int64)	Unique identifier of the customer whose points expiry is updated.
.programId	integer (int64)	Unique identifier of the loyalty program.
.currencyName	string	Unique name of the currency whose expiry is updated.
.pointsExpiryUpdateLogs	object	Object containing details of the points expiry update.
..paType	enum	Type of points awarded to the user. Possible values: `POINT_AWARDED`, `POINT_AWARDED_BILL_PROMOTION`, `POINT_AWARDED_LINEITEM`, `POINT_AWARDED_LINEITEM_PROMOTION`, `POINT_AWARDED_CUSTOMER_PROMOTION`.
..paId	integer (int64)	Unique reference ID is generated when points are awarded to a user.
..expiryUpdateReasonType	enum	Type of expiry modification. Possible values: `EARLY_EXPIRY`, `EXTEND_EXPIRY`.
..expiryUpdateReasonNote	string	Reason for updating the points expiry date.
..oldExpiryDate	date	Points expiry date before the change was requested in ISO 8601 format. Timezone: Cluster-specific timezone. Note: This field will be deprecated in the future and is being replaced by `oldExpiryDateISO`.
..oldExpiryDateISO	date	Indicates the points expiry date before the change was requested in ISO 8601 format, returned in the server timezone. EU server example: 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example: 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response timezone always matches the server timezone, regardless of the timezone offset in the request.
..newExpiryDate	date	Points expiry date after the change was requested in ISO 8601 format. Timezone: Cluster-specific timezone. Note: This field will be deprecated in the future and is being replaced by newExpiryDateISO.
..newExpiryDateISO	date	Indicates the points expiry date after the change was requested in ISO 8601 format, returned in the server timezone. EU server example: 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example: 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response timezone always matches the server timezone, regardless of the timezone offset in the request.
..eventLogId	integer	Unique ID that is generated when the event is triggered.
..eventDate	date	Date when the points expiry update was requested in ISO 8601 format. Timezone: Cluster-specific timezone. Note: This field will be deprecated in the future and is being replaced by `eventDateISO`.
..eventDateISO	date	Indicates the date when the points expiry update was requested in ISO 8601 format, returned in the server timezone. EU server example: 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example: 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response timezone always matches the server timezone, regardless of the timezone offset in the request.
..standardMeta	object	Object containing details of the reason and users who raised and approved the request.
...reason_for_trigger	string	Reason for expiring or extending the points expiry update.
...who_approved	string	Name or username of the user who approved the points expiry update request.
...who_raised	string	Name or username of the user who approved the points expiry update request.
..customMeta	Object	Object containing details of custom metadata.

Note: I also removed the "=" character that was incorrectly placed before "oldExpiryDate" in the original table.

API specific errors

Error Code	Description	Reason
8931	Points expiry update request is invalid or empty	Required fields are invalid or missing
8932	Identifier name is required for the points expiry update	Customer identifier name is invalid or missing
8933	Identifier value is required for the points expiry update	Customer identifier type is invalid or missing
8934	Program ID is required for points expiry update	Program ID provided is missing or invalid.
8935	Invalid standard meta key	Values provided in the `standardMeta` object is invalid or missing.
8936	Points expiry update failed	Operation failed due to some reason. Check if all required parameters are provided and valid.
8937	Points awarded reference ID is required	`pointsAwardedRefId` is missing or invalid.
8938	Points awarded reference type is required	`pointsAwardedRefType` is missing or invalid.
8942	Points expiry date is mandatory	`expiryDate` and its respective arrays are missing or invalid.