Get historical points

Time	Status	User Agent
Retrieving recent requests…

Retrieve historical loyalty points activity imported from an external or legacy loyalty program for a specific customer. The API reads from the historical points log and returns imported entries such as points earned, points redeemed, event dates, and bill numbers.

This API is read-only. It doesn't calculate points or modify balances. If no historical data has been imported for the customer, the API returns an empty array.

Note: This API is for organizations migrating customers from an external or legacy loyalty program. The data reflects points activity imported from the source system, not points earned through the current loyalty program.

Example request

curl -X POST "https://{host}/v2/historicalPoints/getHistoricalPoints/<CUSTOMER_ID>" \
  -H "Authorization: Basic <YOUR_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filterType": "NONE",
      "filterValues": []
    },
    "pageDetails": {
      "offset": 0,
      "limit": 10
    }
  }'

curl -X POST "https://{host}/v2/historicalPoints/getHistoricalPoints/<CUSTOMER_ID>" \
  -H "Authorization: Basic <YOUR_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filterType": "DATE",
      "filterValues": ["2026-01-01T00:00:00+05:30", "2026-12-31T23:59:59+05:30"]
    },
    "pageDetails": {
      "offset": 0,
      "limit": 10
    }
  }'

curl -X POST "https://{host}/v2/historicalPoints/getHistoricalPoints/<CUSTOMER_ID>" \
  -H "Authorization: Basic <YOUR_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filterType": "PROGRAM_ID",
      "filterValues": ["<PROGRAM_ID>"]
    },
    "pageDetails": {
      "offset": 0,
      "limit": 10
    }
  }'

curl -X POST "https://{host}/v2/historicalPoints/getHistoricalPoints/<CUSTOMER_ID>" \
  -H "Authorization: Basic <YOUR_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "filterType": "POINTS_ACTIVITY",
      "filterValues": ["EARNED"]
    },
    "pageDetails": {
      "offset": 0,
      "limit": 10
    }
  }'

Prerequisites

Historical points data must be imported for your organization before this API returns results. If no historical points have been imported, the API returns an empty array.
To import historical points, go to Settings > Master Data Management > Data Import and use the Historical points import profile under the Customer entity.

Path parameters

Field	Type	Required	Description
`customerId`	integer	Required	The internal customer ID of the customer whose historical points you want to retrieve. Returned by the Add Customer or Get Customer APIs.

Body parameters

Field	Type	Required	Description
`filter`	object	Required	Object containing the filter criteria for the request.
`.filterType`	enum	Required	The filter to apply. Must be one of: `NONE`, `DATE`, `TRANSACTION_TYPE`, `BILL_NUMBER`, `LOYALTY_PROGRAM_NAME`, `POINTS_ACTIVITY`, `PROGRAM_ID`. Case-sensitive. See Filter types for details.
`.filterValues`	array	Required	List of values for the selected filter. Pass an empty array `[]` when `filterType` is `NONE`. See Filter types for the required format per filter.
`pageDetails`	object	Required	Object containing pagination settings.
`.offset`	integer	Optional	Number of records to skip. Defaults to `0`.
`.limit`	integer	Required	Maximum number of records to return per page.

Filter types

Filter type	Description	Required `filterValues` format
`NONE`	Returns all historical points records without filtering.	Empty array `[]`
`DATE`	Filters by event date range (inclusive on both ends).	Two ISO 8601 timestamps with timezone offset: `["2026-01-01T00:00:00+05:30", "2026-12-31T23:59:59+05:30"]`. Plain dates (`2026-01-01`) and space-separated formats (`2026-01-01 00:00:00`) are not accepted.
`TRANSACTION_TYPE`	Filters by the type of points transaction.	One or more values: `["CREDIT"]` or `["DEBIT"]`
`BILL_NUMBER`	Filters by bill number. When multiple values are provided, only the first value is used.	One or more bill number strings: `["BILL-12345"]`
`LOYALTY_PROGRAM_NAME`	Filters by the name of the loyalty program in the source system.	One or more program name strings: `["Legacy Loyalty Program"]`
`POINTS_ACTIVITY`	Filters by the points activity label from the source system (for example, `EARNED` or `REDEEMED`).	One or more activity label strings: `["EARNED"]`
`PROGRAM_ID`	Filters by loyalty program ID.	A single numeric value as a string: `["973"]`. Non-integer values return error `2204`.

Example response

{
  "orgId": "<ORG_ID>",
  "customerId": "<CUSTOMER_ID>",
  "historicalPointsData": [
    {
      "entryType": "CREDIT",
      "points": 100.00000,
      "pointsActivity": "EARNED",
      "loyaltyProgramName": "Legacy Loyalty Program",
      "billNumber": "BILL-1001",
      "eventDate": "2026-01-12 00:00:00",
      "externalUniqueId": "<EXTERNAL_ID>",
      "programId": "<PROGRAM_ID>"
    },
    {
      "entryType": "DEBIT",
      "points": 20.00000,
      "pointsActivity": "REDEEMED",
      "loyaltyProgramName": "Legacy Loyalty Program",
      "billNumber": "BILL-1002",
      "eventDate": "2026-01-12 00:00:00",
      "externalUniqueId": "<EXTERNAL_ID>",
      "programId": "<PROGRAM_ID>"
    }
  ],
  "warnings": []
}

Response parameters

Field	Type	Description
`orgId`	integer	ID of the organization.
`customerId`	integer	Internal ID of the customer.
`historicalPointsData`	array	List of historical points entries for the customer. Empty array if no data has been imported.
`.entryType`	string	Possible values: `CREDIT` (points earned), `DEBIT` (points redeemed).
`.points`	decimal	Number of points for this entry.
`.pointsActivity`	string	Points activity label from the source system (for example, `EARNED` or `REDEEMED`). The value is whatever was set during import.
`.loyaltyProgramName`	string	Name of the loyalty program in the source system. The value is whatever was set during import.
`.billNumber`	string	Bill or transaction reference number from the source system.
`.eventDate`	string	Date when the points activity occurred in the source system, in `yyyy-MM-dd HH:mm:ss` format.
`.externalUniqueId`	string	Unique identifier assigned to this record during import, from the source system.
`.programId`	integer	ID of the loyalty program this record is associated with. Returns `-1` if no program ID was set during import.
`warnings`	array	List of warning messages. Empty array if there are no warnings.
`errors`	array	List of error objects. Present only when an error occurs.

Error & warning codes

Code	Error number	Type	Description
`CUSTOMER_NOT_FOUND`	8015	Error	No customer was found for the provided `customerId`. HTTP 200.
`ERR_HISTORICAL_POINTS_FETCH_FAILED`	2204	Error	Failed to fetch historical points. This occurs when `filterValues` are invalid, for example a non-integer value for `PROGRAM_ID`, or a date string that isn't in ISO 8601 format with a timezone offset for `DATE`. HTTP 200.
—	400	Error	The request body is missing a required field. Returned when `filter` or `pageDetails` is omitted entirely.
—	401	Error	Authentication failed. Check your `Authorization` header.