👍
For an overview on our APIs and for hands-on testing, refer to API overview and Make your first API call documentation.

This API retrieves the history of points expiry schedules for a specific duration. The expiry schedules are sorted by date in the ascending order. This is a light API and hence the data retrieval is faster as it shows only the key information of the API.

Prerequisites

Basic or OAuth credentials
Read access to Points access group resource

API endpoint example

https://eu.api.capillarytech.com/v2/customers/565039505/pointsExpirySchedule

curl --location 'https://eu.api.capillarytech.com/v2/customers/565039505/pointsExpirySchedule' \
--header 'Authorization: Basic c2FudC5wXzEyMzpiMmVhMGFhYWI1ZThmODg5ZTAzNGE2NjA5NTIwM2FlNw==' \
--header 'Cookie: _cfuvid=uEUwrBAfGGgkRhH8C6wGyc6ShByhFRsEdpQj1e8WSGU-1750831646379-0.0.1.1-604800000'

Resource Information

URI	v2/customers/565039505/pointsExpirySchedule
HTTP method	GET
Authentication	Basic
Pagination support	No
Rate limit	Yes
Batch Support	No

Query parameters

Parameter (Parameters marked with * are mandatory)	Type	Description
source*	Enum	Source on which the identifier is available. The supported values are FACEBOOK,WEB_ENGAGE,WECHAT, INSTORE,MARTJACK,TMALL,TAOBAO,JD,ECOMMERCE,WEBSITE,LINE, and ALL.
accountId	String	Account ID of a specific source if the source has multiple accounts.
identifierName*	Enum	Identifier type used to fetch the customer's expiry schedule details. The supported values are mobile,email,externalId,cardnumber,cardExternalId.
identifierValue*	String	Identifier of the customer specific to the identifierName.
fetchDataForAllPrograms	Boolean	If `true` Returns expiry schedules for all loyalty programs the customer is enrolled in. If `false` Returns expiry schedules only for the specified programId (or the default program if programId is omitted).
fetchEarliestExpiryOnly	Boolean	When set to true, the API returns the soonest expiry for each unique (programId + pointsType + expiryType) group. When false (default), it returns all expiry schedules for the customer.
startDate	String	Start date (YYYY-MM-DD) for fetching points expiry schedules. Must be future dated (current date + 1 day minimum). Time components not supported. Example: If today is 2023-10-25, earliest allowed is 2023-10-26
endDate	String	End date (YYYY-MM-DD) for the expiry schedule range. Defaults to startDate + 100 years if omitted. Maximum range: 100 years from current date. Time components not supported. Example: With startDate=2023-10-26, maximum endDate is 2123-10-26
programId	String	Unique ID of the program.

Response parameter

Parameter	Type	Description
id	long	Unique identifier.
profiles	array	List containing profile details.
loyaltyInfo	object	Object containing information about loyalty.
loyaltyInfo.loyaltyType	string	Type of loyalty, in this instance, "loyalty".
segments	object	Object containing segment details.
extendedFields	object	Object containing extended field details (currently empty).
expirySchedules	array	List containing details of points expiry schedules.
expirySchedules[].points	float	Number of points in each expiry schedule.
expirySchedules[].expiryDate	string	Date on which the points in each expiry schedule will expire.
expirySchedules[].programId	int	Identifier for the program associated with the points in each expiry schedule.
expirySchedules[].pointsType	string	Type of points in each expiry schedule (e.g., "line_item_regular", "bill_regular").
expirySchedules[].expiryType	string	Type of expiry for the points in each expiry schedule (in this case, "fixed").
warnings	array	List containing warnings related to the entity (currently empty).

Examples

with fetchDataForAllPrograms=false and fetchEarliestExpiryOnly=false

http://{{url}}/v2/customers/lookup/pointsExpirySchedule?identifierName=mobile&identifierValue=919116112960&source=INSTORE&fetchDataForAllPrograms=false&fetchEarliestExpiryOnly=false&programId=1357

{
    "id": 421098436,
    "profiles": [],
    "loyaltyInfo": {
        "loyaltyType": "loyalty"
    },
    "segments": {},
    "extendedFields": {},
    "expirySchedules": [
        {
            "points": 200.0,
            "expiryDate": "2022-05-19",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        },
        {
            "points": 100.0,
            "expiryDate": "2022-05-20",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        }
    ],
    "warnings": []
}

when fetchDataForAllPrograms=true and fetchEarliestExpiryOnly=false

http://{{url}}/v2/customers/lookup/pointsExpirySchedule?identifierName=mobile&identifierValue=919116112960&source=INSTORE&fetchDataForAllPrograms=true&fetchEarliestExpiryOnly=false&programId=1357

{
    "id": 421098436,
    "profiles": [],
    "loyaltyInfo": {
        "loyaltyType": "loyalty"
    },
    "segments": {},
    "extendedFields": {},
    "expirySchedules": [
        {
            "points": 100.0,
            "expiryDate": "2122-03-20",
            "programId": 1356,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        },
        {
            "points": 20.0,
            "expiryDate": "2122-03-20",
            "programId": 1356,
            "pointsType": "bill_regular",
            "expiryType": "fixed"
        },
        {
            "points": 200.0,
            "expiryDate": "2022-05-19",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        },
        {
            "points": 100.0,
            "expiryDate": "2022-05-20",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        }
    ],
    "warnings": []
}

when fetchDataForAllPrograms=false and fetchEarliestExpiryOnly=true

http://{{url}}/v2/customers/lookup/pointsExpirySchedule?identifierName=mobile&identifierValue=919116112960&source=INSTORE&fetchDataForAllPrograms=false&fetchEarliestExpiryOnly=true&programId=1357

{
    "id": 421098436,
    "profiles": [],
    "loyaltyInfo": {
        "loyaltyType": "loyalty"
    },
    "segments": {},
    "extendedFields": {},
    "expirySchedules": [
        {
            "points": 200.0,
            "expiryDate": "2022-05-19",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        }
    ],
    "warnings": []
}

when fetchDataForAllPrograms=true and fetchEarliestExpiryOnly=true

http://{{url}}/v2/customers/lookup/pointsExpirySchedule?identifierName=mobile&identifierValue=919116112960&source=INSTORE&fetchDataForAllPrograms=true&fetchEarliestExpiryOnly=true&programId=1357

{
    "id": 421098436,
    "profiles": [],
    "loyaltyInfo": {
        "loyaltyType": "loyalty"
    },
    "segments": {},
    "extendedFields": {},
    "expirySchedules": [
        {
            "points": 100.0,
            "expiryDate": "2122-03-20",
            "programId": 1356,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        },
        {
            "points": 20.0,
            "expiryDate": "2122-03-20",
            "programId": 1356,
            "pointsType": "bill_regular",
            "expiryType": "fixed"
        },
        {
            "points": 200.0,
            "expiryDate": "2022-05-19",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        }
    ],
    "warnings": []
}

with startDate and endDate

http://{{url}}/v2/customers/lookup/pointsExpirySchedule?identifierName=mobile&identifierValue=919116112960&source=INSTORE&startDate=2020-01-01&endDate=2040-03-01&programId=1357&fetchEarliestExpiryOnly=false&fetchDataForAllPrograms=true

{
    "id": 421098436,
    "profiles": [],
    "loyaltyInfo": {
        "loyaltyType": "loyalty"
    },
    "segments": {},
    "extendedFields": {},
    "expirySchedules": [
        {
            "points": 200.0,
            "expiryDate": "2022-05-19",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        },
        {
            "points": 100.0,
            "expiryDate": "2022-05-20",
            "programId": 1357,
            "pointsType": "line_item_regular",
            "expiryType": "fixed"
        }
    ],
    "warnings": []
}

API specific error code

Error Code	Description	Reason
8015	Customer not found for the given identifiers	Invalid or missing customer identifier passed
8003	Invalid source	Unsupported source parameter passed
8130	Lookup,Invalid Params passed	Unsupported query parameter passed
1216	The date format used for startDate is not supported. Enter the date in (yyyy-MM-dd) format The date format used for endDate is not supported. Enter the date in (yyyy-MM-dd) format	Incorrect format given for `startDate` and `endDate` parameter
1215	startDate cannot be in past	Past date given for `startDate` parameter
1214	startDate is after endDate	Date provided in `startDate` parameter is beyond the end date
1217	endDate cannot be after 100 years from now	Date provided for `endDate` is beyond 100 years
885	Invalid program id passed	Unsupported program Id