get https://{host}/v2.1/pointsLedger/getCustomerLedgerInfo
This API fetches the ledger information of a customer registered in a connected organisation.
A customer points ledger is essentially a record that tracks the points earned, spent, and adjusted within an organization and its affiliates. These points are treated like currency and can be redeemed across various units or loyalty programs within the organization.
For more information, refer to the documentation on Points Ledgers.
Note
For detailed information about our APIs and for hands-on testing, refer to the documentation in API overview and step-by-step guide on making your first API call.
Prerequisites
- Authentication: Basic or OAuth credentials
- Access to the Points Access group. 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
'https://eucrm.cc.capillarytech.com/v2.1/pointsLedger/getCustomerLedgerInfo?identifierName=mobile&identifierValue=917406401004&source=INSTORE'
Headers
| Header | Description |
|---|---|
| DATA-SCOPE-ORG | List of Organization IDs |
| DATA-SCOPE | Scopes define what data can be accessed using the API. You can use scopes to control access to data from a parent or child organization. Defining a scope ensures that the response contains only data from the respective organization. Supported headers: SELF and OTHER.Refer to connected orgs data scopes for more information. |
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 of the customer. Supported values mobile , id, email and externalid |
| identifierValue* | Value for the identifier. For example, the mobile number or customer ID. |
| source* | Source in which the identifier is available. For example, instore, martjack, wechat, facebook, web_engage, tmall, taobao, jd, ecommerce, website, line, all |
| accountId* | For sources with multiple accounts, pass the specific accountId for the source. |
| tillId | A customer till is the point of sale (POS) system used in a store. Use the get active tills API to get the active tills for the organisation. |
| limit | The number of results to retrieve. |
| offset | Page number to retrieve. |
| programId | Retrieve the ledger details of a specific program. A loyalty program encourages customers to continue shopping or using services by offering rewards, discounts, or special incentives for frequent purchases. |
| isFilterBasedOnDate | Indicates whether the date filter is applied when fetching data. If the start date and end date are not included in the API request, isFilterBasedOnDate is false, and the API retrieves the user’s entire purchase history.Default value: true |
| includeLastOneYearData | If includeLastOneYearData is true, the API response includes data from the last year instead of the last 90 days when only startDate or endDate is included in the API query parameters.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. Note: - The maximum difference between startDate and endDate must not exceed 90 days.- If only startDate or endDate is included in the API query parameters, the ledger data for 90 days is retrieved based on the provided startDate or endDate.If includeLastOneYearData is true, the API response includes data from the last year instead of the last 90 days.- When startDate and endDate are not included in the API request parameters, isFilterBasedOnDate is false, and the API retrieves 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. Note: - The maximum difference between startDate and endDate must not exceed 90 days.- If only startDate or endDate is included in the API query parameters, the ledger data for 90 days is retrieved based on the provided startDate or endDate.If includeLastOneYearData is true, the API response includes data from the last year instead of the last 90 days.- When startDate and endDate are not included in the API request parameters, isFilterBasedOnDate is false, and the API retrieves the user’s entire past purchase history. |
| includeTillConceptEvents | Set the value as true to fetch deduction entries triggered at tills mapped to the concept event of the Program ID, even if the deductions are from a different program.When set to true, set the programId value; otherwise, it will be considered an invalid input combination.The default value is false. |
| 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 to 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 using this. If the value is true, includeAlternateCurrencies lists all the available currencies. |
Query parameter (User group)
You can use the below query parameters and retrieve points ledger entries of a usergroup.
| Parameter (Parameters marked with * sign are mandatory) | Description |
|---|---|
| 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* | Source in which the identifier is available. 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. |
| 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. |
{
"customerDetails": {
"firstName": "Porter",
"lastName": "Robinson",
"userId": 3923627848,
"entityType": "CUSTOMER"
},
"ledgerDetails": {
"pageNumber": 0,
"pageSize": 10,
"totalEntries": 2,
"pageCount": 1,
"ledgerClosingBalance": []
},
"ledgerEntries": [
{
"eventLogId": 13499091,
"eventName": "TransactionAdd",
"customerId": 347297848,
"ledgerCreatedDate": "2024-08-30 11:17:57.0",
"customerDetails": {
"userId": 0
},
"entryDetails": [
{
"ledgerEntryType": "CREDIT",
"points": "100.000",
"pointsCategory": "Main",
"programName": "ChildOrg1DefaultProgram",
"programId": 1148
}
],
"netPointsOnEvent": "100.000",
"transactionDetails": {
"transactionId": 36363905,
"transactionNumber": "1725016677",
"date": "2024-08-30 11:17:57.0",
"amount": 5000.0,
"grossBillAmount": 5000.0,
"source": "instore"
},
"store": "Store1",
"storeCode": "store1",
"tillCode": "childorgtill1",
"eventDetails": {},
"sourceProgramId": 1148,
"sourceProgramName": "ChildOrg1DefaultProgram",
"orgId": 50406
},
{
"eventLogId": 13499017,
"eventName": "CustomerRegistration",
"customerId": 347297848,
"ledgerCreatedDate": "2024-08-30 11:09:02.0",
"customerDetails": null,
"entryDetails": [
{
"ledgerEntryType": "OPENING_BALANCE",
"points": "0.000",
"pointsCategory": "DelayedAccrualPointCategory",
"programName": "ChildOrg1DefaultProgram",
"programId": 1148
},
{
"ledgerEntryType": "OPENING_BALANCE",
"points": "0.000",
"pointsCategory": "ExternalTriggerBasedPointCategory",
"programName": "ChildOrg1DefaultProgram",
"programId": 1148
},
{
"ledgerEntryType": "OPENING_BALANCE",
"points": "0.000",
"pointsCategory": "Main",
"programName": "ChildOrg1DefaultProgram",
"programId": 1148
}
],
"netPointsOnEvent": "0.000",
"transactionDetails": {},
"store": "Store1",
"storeCode": "store1",
"tillCode": "childorgtill1",
"eventDetails": {},
"sourceProgramId": 1148,
"sourceProgramName": "ChildOrg1DefaultProgram",
"orgId": 50406
}
],
"warnings": []
}
{
"customerDetails": {
"firstName": "Porter",
"lastName": "Robinson",
"userId": 341257848,
"entityType": "CUSTOMER"
},
"ledgerDetails": {
"pageNumber": 0,
"pageSize": 10,
"totalEntries": 1,
"pageCount": 1,
"ledgerClosingBalance": []
},
"ledgerEntries": [
{
"eventLogId": 13499088,
"eventName": "TransactionAdd",
"customerId": 347297848,
"ledgerCreatedDate": "2024-08-30 11:15:48.0",
"customerDetails": {
"userId": 0
},
"entryDetails": [
{
"ledgerEntryType": "OPENING_BALANCE",
"points": "0.000",
"pointsCategory": "DelayedAccrualPointCategory",
"programName": "ParentOrgDefaultProgram",
"programId": 1147
},
{
"ledgerEntryType": "OPENING_BALANCE",
"points": "0.000",
"pointsCategory": "ExternalTriggerBasedPointCategory",
"programName": "ParentOrgDefaultProgram",
"programId": 1147
},
{
"ledgerEntryType": "OPENING_BALANCE",
"points": "0.000",
"pointsCategory": "Main",
"programName": "ParentOrgDefaultProgram",
"programId": 1147
},
{
"ledgerEntryType": "CREDIT",
"points": "50.000",
"pointsCategory": "Main",
"programName": "ParentOrgDefaultProgram",
"programId": 1147
}
],
"netPointsOnEvent": "50.000",
"transactionDetails": {
"transactionId": 36363904,
"transactionNumber": "1725016548",
"date": "2024-08-30 11:15:48.0",
"amount": 6000.0,
"grossBillAmount": 6000.0,
"source": "instore"
},
"store": "Store1",
"storeCode": "store1",
"tillCode": "parentorgtill1",
"eventDetails": {},
"sourceProgramId": 1147,
"sourceProgramName": "ParentOrgDefaultProgram",
"orgId": 50405
}
],
"warnings": []
}
Response parameter (Customer)
| Parameter | Description |
|---|---|
| customerDetails | Details of the current customer. |
| firstName | First name of the customer. |
| lastName | Last name of the customer. |
| userId | Unique user ID of the customer. |
| externalId | External ID of the customer. A customer external ID is a unique identifier that can be manually generated and tagged to a customer during registration. |
| 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. Custom Date Format |
| 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. |
| sourceProgramId | The identifier of the source program associated with the entry. |
| sourceProgramName | The name of the source program associated with the entry. |
| orgID | Unique ID of the organization. |
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. Custom Date Format |
| 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. |
| orgID | Unique ID of the organization. |
| sourceProgramId | The identifier of the source program associated with the entry. |
| sourceProgramName | The name of the source program associated with the entry. |
| warnings | An array containing any warning messages. |
API specific error codes
| Error | Description |
|---|---|
| 8013 | Identifier name missing or incorrect. |
| 8015 | Identifier value missing or incorrect. |
| 8003 | Source is missing or incorrect. |
| 310144 | Connected Orgs not set properly in Headers. Check whether the target organisation is a connected organisation. |