Get Points Ledger Information

get https://{host}/v2/pointsLedger/getCustomerLedgerInfo

Retrieves the points ledger records of a customer, usergroup or alternate currencies for each event.

👍
For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

Prerequisites

Make sure you have access to the Points access group resource. For more information, see access group documentation.

API Specification


HTTP Method	GET
Pagination	Yes
Batch support	No
Rate limit information	Refer to rate limit documentation .

API endpoint example

Retrieve points ledger entries of a User group - /v2/pointsLedger/getCustomerLedgerInfo?type=USERGROUP2&identifierName=id&identifierValue=381335652&source=INSTORE&offset=0&limit=10&sortOrder=ASC
Retrieve points ledger entries of a customer - v2/pointsLedger/getCustomerLedgerInfo?identifierName=id&identifierValue=98662653&source=INSTORE&limit=10
Retrieve points ledger entries of Alternate Currencies for a customer- /v2/pointsLedger/getCustomerLedgerInfo?identifierName=id&identifierValue=423725119&source=INSTORE&includeAlternateCurrencies=true or /v2/pointsLedger/getCustomerLedgerInfo?identifierName=id&identifierValue=423725119&source=INSTORE&alternateCurrencyNames=acNjnkvfgfdeun

Query parameter (Customer)

You can use the below query parameters and retrieve points ledger entries of a customer.

Parameter (Parameters marked with * sign are mandatory)	Description
identifierName*	Identifier type to identify the customer. (id, email, mobile, externalId)
identifierValue*	Value of the specified identifier type of the customer.
source*	Source in which the identifier is available.
acountId*	For sources with multiple accounts, pass the specific accountId.
tillId	Get the customer’s ledger information of a specific TILL. Pass the unique till ID.
limit	Number of ledger records to display per page. For example, if the total records are fifteen and the limit is five, the first page will display the first five records only. The maximum supported limit is 100.
offset	Page number to retrieve. To view the first page, set the value to `0`.
programId	Retrieve the ledger details of a specific program.
isFilterBasedOnDate	Indicates whether the date filter should be applied when fetching data from the database. When the start date and end date are not passed in the API request parameters, the value of isFilterBasedOnDate becomes false and the API fetches the user’s entire past purchase history. Default value: True
includeLastOneYearData	If `includeLastOneYearData` is set to true, the API response will include data from the last year instead of the last 90 days when only startDate or endDate is passed in the API query parameter. Default value: False
startDate	Get ledger information from on or after a specific date. Pass the start date in YYYY-MM-DDThh:mm:ss format. Notes: - The maximum difference between startDate and endDate should not be more than 90 days. - If only startDate or endDate is passed in the API query parameter, the ledger data for 90 days is retrieved based on the provided startDate or endDate. If `includeLastOneYearData` is set to true, the API response will include data from the last year instead of the last 90 days. - When the start date and end date are not passed in the API request parameters, the value of `isFilterBasedOnDate` becomes false and the API fetches the user’s entire past purchase history.
endDate	Get ledger information until a specific date. Pass the end date in YYYY-MM-DDThh:mm:ss format. Notes: - The maximum difference between startDate and endDate should not be more than 90 days. - If only startDate or endDate is passed in the API query parameter, the ledger data for 90 days is retrieved based on the provided startDate or endDate.. If `includeLastOneYearData` is set to true, the API response will include data from the last year instead of the last 90 days. -When the start date and end date are not passed in the API request parameters, the value of `isFilterBasedOnDate` becomes false and the API fetches the user’s entire past purchase history.
includeTillConceptEvents	Pass true to fetch deduction entries that were triggered at the tills mapped to the Concept of the Program ID even if the deductions are from a different program. Default value is false. When true, pass the programId also, else it will be qualified as invalid input combination.
ledgerEntryType	Specify the type of ledger entries you want to fetch. Supported values: CREDIT, DEBIT, OPENING_BALANCE. By default, it fetches all the ledger entry types.
pointCategoryType	Specify the point category type for which you want to fetch ledger details. Supported values: REGULAR, PROMISED, TRIGGER_BASED. By default, it fetches all the points category details.
includeAlternateCurrencies	Set includeAlternateCurrencies=true to retrieve all alternate currencies available with the customer.
alternateCurrencyNames	Filter alternate currencies for the customer based on the name. You can also pass a list of comma-separated alternate currency names. Set the parameter includeAlternateCurrencies to false when you use this. If the value is true, includeAlternateCurrencies lists all the available currencies.
excludePointCategories	You can use this parameter with `includeAlternateCurrencies=true` to include ledger records only with respect to alternate currencies. Refer to the behaviour of alternate currency and point category parameters section for more information.

You can use the below query parameters and retrieve points ledger entries of a usergroup.

Parameter (Parameters marked with * sign are mandatory)	Description
type	Type of entity.
identifierName*	The identifier of the group to search for the ledger information. The following identifiers are applicable: groupId, externalId, and primaryUserId
identifierValue*	The value of the identifier.
source*	The origin of the information. For example, INSTORE, MARTJACK, WECHAT, FACEBOOK , WEB_ENGAGE, , TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, ALL
limit	The maximum number of items to be retrieved.
includeAlternateCurrencies	Set includeAlternateCurrencies=true to retrieve all alternate currencies available with the group.
alternateCurrencyNames	Filter alternate currencies for the customer based on the name. You can also pass a list of comma-separated alternate currency names. Set the parameter includeAlternateCurrencies to false when you use this. If the value is true, includeAlternateCurrencies lists all the available currencies.
excludePointCategories	You can use this parameter with `includeAlternateCurrencies=true` to include ledger records only with respect to alternate currencies. Refer to the behaviour of alternate currency and point category parameters section for more information.
offset	The starting index for data retrieval.
sort	Sort the order of entries from date. The supported values are ASC and DESC.
role	These are the roles defined by the brands for members in a user group. For example, PRIMARY, SECONDARY, and so on.

Behaviour of alternate currency and point category parameters

The following table details how different combinations of includeAlternateCurrencies, pointCategoryType, and excludePointCategories the parameters affect the API response:

`includeAlternateCurrencies`	`pointCategoryType`	`excludePointCategories`	Behaviour
`true`	`REGULAR`, `PROMISED`, or `TRIGGER_BASED`	Not provided/ `false`	Only points and alternate currencies entries with the provided category types are displayed.
`true`	Not provided	Not provided/ `false`	Points and alternate currencies across all categories are displayed.
`true`	Not provided	`true`	Only alternate currency entries are displayed.
`true`	`REGULAR`	`true`	Only alternate currency entries are displayed; `pointCategoryType` is ignored when `excludePointCategories=true`.
`false`	Not provided	Not provided/ `false`	Only entries for points across all categories are displayed.
`false`	`REGULAR`, `PROMISED`, or `TRIGGER_BASED`	Not provided/ `false`	Only entries matching the provided point category types are displayed, excluding alternate currencies.

Response parameter (Customer)

Parameter	Description
customerDetails	Details of the current customer.
firstName	Name of the customer.
lastName	Last name of the customer.
userId	Unique ID of the customer.
externalId	External ID of the customer.
entityType	Whether the points are issued to an individual (CUSTOMER), or group (FLEET).
pageNumber	Current page number. Default value - 0 (first page).
pageSize	Number of entries shown on the current page.
totalEntries	Total number of ledger entries available for the customer.
pageCount	Total number of pages according to the page size.
eventLogId	Unique log ID of the current event.
eventName	Name of the event associated with the points. Example - TransactionAdd, PointsRedemption, DelayedAccrual, PointsExpiry, CustomerRegistration, ReturnBill.
ledgerCreatedDate	Date and time when the points ledger entry was created.
entryDetails	Details of the points ledger.
ledgerClosingBalance	Details of closing ledger balance on a specific date.
pointsCategory	Category from which points are issued. Supported values: Main (redeemable account), DelayedAccrualPointCategory (promised points), ExternalTriggerBasedPointCategory (promised points).
programName	Name of the loyalty program associated with points.
programId	Unique ID of the loyalty program.
closingBalance	Available closing balance on that particular end date.
netPointsOnEvent	Net points in the current event (by adding credits and subtracting debits).
transactionDetails	Transaction details of the current points. Applicable for transaction related events.
transactionId	Transaction ID associated with the points.
transactionNumber	Transaction number associated with the points.
date	Date of the transaction.
amount	Net transaction amount.
store	Name of the store associated with the points.
storeCode	Unique code of the store associated with points.
tillCode	Unique TILL code associated with points.

Response parameter (User group)

Parameter	Description
ledgerDetails	Contains details about the pagination of the ledger entries.
pageNumber	The current page number in the pagination.
pageSize	The number of entries per page in the pagination.
totalEntries	The total number of entries in the ledger.
pageCount	The total number of pages in the pagination.
ledgerEntries	An array containing the ledger entries.
eventLogId	A unique identifier for the event.
eventName	The name of the event.
customerId	The identifier of the customer associated with the event.
ledgerCreatedDate	The date and time when the ledger entry was created.
customerDetails	Details of the customer.
entryDetails	An array containing the details about the ledger entry.
ledgerEntryType	The type of the ledger entry.
points	The number of points associated with the entry.
pointsCategory	The category of the points.
programName	The name of the program associated with the entry.
programId	The identifier of the program is associated with the entry.
alternateCurrencyName	Alternate currency name. This is visible when you query for the alternate currency ledger for a customer.
netPointsOnEvent	The net points associated with the event.
transactionDetails	Details about the transaction.
store	The store associated with the event.
storeCode	The code of the store associated with the event.
tillCode	The code of the till associated with the event.
eventDetails	Details about the event.
reason	The reason for the event.
warnings	An array containing any warning messages.

{
    "customerDetails": {
        "firstName": "naresh",
        "lastName": "silla",
        "userId": 64035151,
        "entityType": "CUSTOMER"
    },
    "ledgerDetails": {
        "pageNumber": 0,
        "pageSize": 10,
        "totalEntries": 34,
        "pageCount": 4
    },
    "ledgerEntries": [
        {
            "eventLogId": 183281908,
            "eventName": "GenericEvent",
            "customerId": 64035151,
            "ledgerCreatedDate": "2024-05-04 07:16:34.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Tier-points"
                }
            ],
            "netPointsOnEvent": "100.000",
            "transactionDetails": {},
            "store": "default",
            "storeCode": "default",
            "tillCode": "default",
            "eventDetails": {
                "eventDisplayName": "ThankYouSanta",
                "displayName": "ThankYouSanta"
            },
            "sourceProgramId": 817,
            "sourceProgramName": "David Jones- Card Program"
        },
        {
            "eventLogId": 183267939,
            "eventName": "GenericEvent",
            "customerId": 64035151,
            "ledgerCreatedDate": "2024-05-04 06:35:44.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "OPENING_BALANCE",
                    "points": "0.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Pebbles"
                },
                {
                    "ledgerEntryType": "OPENING_BALANCE",
                    "points": "0.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Boost"
                },
                {
                    "ledgerEntryType": "OPENING_BALANCE",
                    "points": "0.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Tier-points"
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Tier-points"
                }
            ],
            "netPointsOnEvent": "100.000",
            "transactionDetails": {},
            "store": "default",
            "storeCode": "default",
            "tillCode": "default",
            "eventDetails": {
                "eventDisplayName": "ThankYouSanta",
                "displayName": "ThankYouSanta"
            },
            "sourceProgramId": 817,
            "sourceProgramName": "David Jones- Card Program"
        },
        {
            "eventLogId": 178283044,
            "eventName": "BulkAllocatePoints",
            "customerId": 626,
            "ledgerCreatedDate": "2024-04-19 07:39:11.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "2000.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                }
            ],
            "netPointsOnEvent": "2000.000",
            "transactionDetails": {},
            "store": "default",
            "storeCode": "default",
            "tillCode": "default",
            "eventDetails": {},
            "sourceProgramId": 626,
            "sourceProgramName": "David Jones- Default Program"
        },
        {
            "eventLogId": 178283042,
            "eventName": "TransactionAdd",
            "customerId": 64035151,
            "ledgerCreatedDate": "2024-04-19 07:39:12.0",
            "customerDetails": {
                "userId": 0
            },
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "20.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stars"
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stamps"
                }
            ],
            "netPointsOnEvent": "220.000",
            "transactionDetails": {
                "transactionId": 130717557,
                "transactionNumber": "1542280708645",
                "date": "2024-04-19 07:39:11.0",
                "amount": 200.0,
                "grossBillAmount": 200.0,
                "source": "instore"
            },
            "store": "supermarketdemo",
            "storeCode": "supermarketdemo",
            "tillCode": "till.marketsuper",
            "eventDetails": {},
            "sourceProgramId": 817,
            "sourceProgramName": "David Jones- Card Program"
        },
        {
            "eventLogId": 178282122,
            "eventName": "BulkAllocatePoints",
            "customerId": 626,
            "ledgerCreatedDate": "2024-04-19 07:36:17.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "2000.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                }
            ],
            "netPointsOnEvent": "2000.000",
            "transactionDetails": {},
            "store": "default",
            "storeCode": "default",
            "tillCode": "default",
            "eventDetails": {},
            "sourceProgramId": 626,
            "sourceProgramName": "David Jones- Default Program"
        },
        {
            "eventLogId": 178282119,
            "eventName": "TransactionAdd",
            "customerId": 64035151,
            "ledgerCreatedDate": "2024-04-19 07:36:18.0",
            "customerDetails": {
                "userId": 0
            },
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "20.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stars"
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stamps"
                }
            ],
            "netPointsOnEvent": "220.000",
            "transactionDetails": {
                "transactionId": 130716752,
                "transactionNumber": "1542280708644",
                "date": "2024-04-19 07:36:17.0",
                "amount": 200.0,
                "grossBillAmount": 200.0,
                "source": "instore"
            },
            "store": "supermarketdemo",
            "storeCode": "supermarketdemo",
            "tillCode": "till.marketsuper",
            "eventDetails": {},
            "sourceProgramId": 817,
            "sourceProgramName": "David Jones- Card Program"
        },
        {
            "eventLogId": 178277003,
            "eventName": "BulkAllocatePoints",
            "customerId": 626,
            "ledgerCreatedDate": "2024-04-19 07:21:31.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "2000.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                }
            ],
            "netPointsOnEvent": "2000.000",
            "transactionDetails": {},
            "store": "default",
            "storeCode": "default",
            "tillCode": "default",
            "eventDetails": {},
            "sourceProgramId": 626,
            "sourceProgramName": "David Jones- Default Program"
        },
        {
            "eventLogId": 178276992,
            "eventName": "TransactionAdd",
            "customerId": 64035151,
            "ledgerCreatedDate": "2024-04-19 07:21:32.0",
            "customerDetails": {
                "userId": 0
            },
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "20.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stars"
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stamps"
                }
            ],
            "netPointsOnEvent": "220.000",
            "transactionDetails": {
                "transactionId": 130712377,
                "transactionNumber": "1542280708643",
                "date": "2024-04-19 07:21:29.0",
                "amount": 200.0,
                "grossBillAmount": 200.0,
                "source": "instore"
            },
            "store": "supermarketdemo",
            "storeCode": "supermarketdemo",
            "tillCode": "till.marketsuper",
            "eventDetails": {},
            "sourceProgramId": 817,
            "sourceProgramName": "David Jones- Card Program"
        },
        {
            "eventLogId": 178061276,
            "eventName": "BulkAllocatePoints",
            "customerId": 626,
            "ledgerCreatedDate": "2024-04-18 11:53:07.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "2000.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                }
            ],
            "netPointsOnEvent": "2000.000",
            "transactionDetails": {},
            "store": "default",
            "storeCode": "default",
            "tillCode": "default",
            "eventDetails": {},
            "sourceProgramId": 626,
            "sourceProgramName": "David Jones- Default Program"
        },
        {
            "eventLogId": 178061275,
            "eventName": "TransactionAdd",
            "customerId": 64035151,
            "ledgerCreatedDate": "2024-04-18 11:53:07.0",
            "customerDetails": {
                "userId": 0
            },
            "entryDetails": [
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "20.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stars"
                },
                {
                    "ledgerEntryType": "CREDIT",
                    "points": "100.000",
                    "pointsCategory": "Main",
                    "programName": "David Jones- Default Program",
                    "programId": 626,
                    "alternateCurrencyName": "Stamps"
                }
            ],
            "netPointsOnEvent": "220.000",
            "transactionDetails": {
                "transactionId": 130540500,
                "transactionNumber": "1542280708642",
                "date": "2024-04-18 11:53:06.0",
                "amount": 200.0,
                "grossBillAmount": 200.0,
                "source": "instore"
            },
            "store": "supermarketdemo",
            "storeCode": "supermarketdemo",
            "tillCode": "till.marketsuper",
            "eventDetails": {},
            "sourceProgramId": 817,
            "sourceProgramName": "David Jones- Card Program"
        }
    ],
    "warnings": []
}

{
    "customerDetails": {
        "firstName": "Kamal",
        "lastName": "H",
        "userId": 170940055,
        "externalId": "000000043488",
        "entityType": "CUSTOMER"
    },
    "ledgerDetails": {
        "pageNumber": 0,
        "pageSize": 10,
        "totalEntries": 1,
        "pageCount": 1
    },
    "ledgerEntries": [
        {
            "eventLogId": 569437706,
            "eventName": "CustomerUpdate",
            "customerId": 170940055,
            "ledgerCreatedDate": "2024-04-25 14:34:52.0",
            "customerDetails": null,
            "entryDetails": [
                {
                    "ledgerEntryType": "OPENING_BALANCE",
                    "points": "0.00",
                    "pointsCategory": "Main",
                    "programName": "Default Program",
                    "programId": 469,
                    "alternateCurrencyName": "Stars"
                },
                {
                    "ledgerEntryType": "OPENING_BALANCE",
                    "points": "0.00",
                    "pointsCategory": "Main",
                    "programName": "Default Program",
                    "programId": 469,
                    "alternateCurrencyName": "Coins"
                }
            ],
            "netPointsOnEvent": "0.000",
            "transactionDetails": {},
            "store": "demostorebukl Mobile",
            "storeCode": "demostorebukl",
            "tillCode": "demostorebukl.1",
            "eventDetails": {},
            "sourceProgramId": 805,
            "sourceProgramName": "Seven Entertainment",
            "orgId": null
        }
    ],
    "warnings": []
}

API error codes

Error Code	Description	Reason
11012	Invalid userId passed in request	The userId is wrong.
8013	Lookup, Invalid identifier passed	The identifier type is wrong or invalid
11029	Limit cannot be greater than 100	The page limit is higher than the supported limit
11003	There are no ledger entries present for the given parameters. Try removing parameters to widen the search	The offset value is greater than the total number of pages.
11007	Invalid ledgerEntryType passed in request	The type of ledger entry is wrong or invalid.
11008	Invalid pointCategoryType passed in request	The type of point category is wrong or invalid.
9003	No CPS entry for the given points type.	No matching record found in the Customer Points Summary (CPS) table for that specific combination of customer and points type. Verify the customer ID is correct and confirm the points type is valid. Contac Capillary support team if the issue persists.