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

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

{
    "expiryDateUpdateRequest": [
        {
            "identifierName": "id",
            "identifierValue": "172440986",
            "programId": 469,
            "pointsAwardedRefId": 117521910,
            "pointsAwardedRefType": "POINT_AWARDED",
            "expiryUpdateReasonType": "EXTEND_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"
            }
        }
    ]
}

{
    "expiryDateUpdateRequest": [
        {
            "identifierName": "id",
            "identifierValue": "172440986",
            "programId": 469,
            "pointsAwardedRefId": 117521910,
            "pointsAwardedRefType": "POINT_AWARDED",
            "expiryUpdateReasonType": "EXTEND_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_DAYS",
     		    "expiryValue": "30"

            }
        }
    ]
}

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.
`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	No	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": "EXTEND_EXPIRY",
                "expiryUpdateReasonNote": "xyz",
                "oldExpiryDate": "2022-12-31 23:59:59",
                "newExpiryDate": "2025-08-09 23:59:59",
                "eventLogId": 41420339,
                "eventDate": "2025-07-07 06:39:11",
                "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.
newExpiryDate	date	Points expiry date after the change was requested in ISO 8601 format. Timezone: Cluster-specific timezone.
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.
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.

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.