Use the v2/getHistoricalPoints POST API is used to retrieve historical loyalty points activity for a specific customer.

This API reads from the Historical Points Log and returns imported points entries, such as:

Points earned (CREDIT)
Points redeemed (DEBIT)
Event date
Points activity (Earned/Burned, etc)
Bill number

The API supports filtering by:

Date range
Transaction type (CREDIT or DEBIT)
Bill number
No filter (retrieve all records)

📘
Notes

Use pagination to control the number of records returned per request.

This API is read-only. It does not calculate points or modify balances. It only returns data previously imported into the system.

If no historical data exists for the customer, the API returns an empty array.

BusinessCase: Display six-month loyalty ledger

The business requires the loyalty application to display a customer’s ledger for the last six months from the current date.

The system must maintain and retrieve 180 days of historical ledger entries to support this rolling six-month view.

The ledger view must present consistent data across web and mobile channels.

Prerequisites

Historical points data must be imported for your organization. If no historical points have been imported, the API returns an empty array.
Configure historical points import using the Data Import Framework. The "Historical points import" profile is available under the Customer entity. Access Settings > Master Data Management > Data Import and select the appropriate profile.

📘
Note
This API is for organizations migrating customers from an external or legacy loyalty program to Capillary. The data reflects points activity (credits and debits) imported from the source system.

Example request

curl --location 'https://eu.intouch.capillarytech.com/v2/historicalPoints/getHistoricalPoints/564582355' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmVZhNGNjZGMzMzQzMWVmOWFjOQ==' \
--data '{
    "filter":{
        "filterType":"DATE", 
        "filterValues":[
       "2024-06-30T00:00:00+05:30",
  "2024-07-02T00:00:00+05:30"
]
         
    },
    "pageDetails":{
            "offset":0,
            "limit": 10
        }
    
        
}'

curl --location 'https://eu.intouch.capillarytech.com/v2/historicalPoints/getHistoricalPoints/564582355' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic mOWFjOQ==' \
--data '{
    "filter":{
        "filterType":"NONE"
        
    },
    "pageDetails":{
            "offset":0,
            "limit": 10
        }
    
            
}'

curl --location 'https://eu.intouch.capillarytech.com/v2/historicalPoints/getHistoricalPoints/564582355' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmVlcmFqLmZhNGNjZGMzMzQzMWVmOWFjOQ==' \
--data '{
    "filter":{
        "filterType":"BILL_NUMBER", 
        "filterValues":[
       "BILL240302"
]
         
    },
    "pageDetails":{
            "offset":0,
            "limit": 10
        }
    
        
}'

Path parameters

Parameter	Type	Required	Description
Customer ID	Integer	Yes	Unique identifier of the customer whose historical points data you want to retrieve.

Body parameters

🚧
These are query parameters but defined in the body section of the API.

Parameter	Type	Required	Description
filter	object	Yes	Filter criteria for narrowing down results.
.filterType	string	Yes	Type of filter to apply. Supported values: `TRANSACTION_TYPE`, `DATE`, `BILL_NUMBER`, `NONE`. Any of the filters is mandatory.
.filterValues	array	Yes	List of values to filter by. Pass empty array `[]` when filterType is `NONE`.
pageDetails	object	Yes	Pagination settings.
.offset	integer	Optional	Number of records to skip. The count starts from 0.
.limit	integer	Yes	Maximum number of records to return per page.

Filter types

Filter Type	Description	Example filterValues
TRANSACTION_TYPE	Filters by the type of points transaction (credit or debit).	`["CREDIT"]` or `["DEBIT"]`
DATE	Filters by event timestamp in an inclusive time range (start and end both inclusive). Requires two ISO‑8601 date‑time values with timezone.	`["2024-07-01T00:00:00+05:30", "2024-07-02T00:00:00+05:30"]
BILL_NUMBER	Filters by bill number. If multiple bill numbers are provided, only the first bill number is considered.	`["BILL12345"]`
NONE	Returns all historical points without filtering.	`[]`

Example response

{
    "orgId": 50224,
    "customerId": 348918999,
    "historicalPointsData": [
        {
            "entryType": "DEBIT",
            "points": 20.00000,
            "pointsActivity": "null",
            "loyaltyProgramName": "null",
            "billNumber": "538579470",
            "eventDate": "2026-01-12 00:00:00",
            "externalUniqueId": "test3"
        }
    ],
    "warnings": []
}

Response parameters

Parameter	Datatype	Description
-orgId	integer	Organization ID.
-customerId	integer	Unique identifier of the customer.
-historicalPointsData	array	List of historical points entries.
--entryType	string	Type of points transaction: `CREDIT` (points earned) or `DEBIT` (points redeemed).
--points	decimal	Number of points for this entry.
--pointsActivity	string	Description of the points activity from the legacy system.
--billNumber	string	Bill or transaction reference number.
--eventDate	string	Date when the points activity occurred in the source system in the format you imported the data. Ex- yyyy-MM-dd HH:mm:ss format.
externalUniqueId	string	External unique ID of the customer provided during the import.
warnings	array	List of warning messages.
errors	array	List of error messages.

API specific error code

Error Code	Description	Reason
8015	Customer not found for the given identifiers	Invalid or missing customerId.