get https://{host}/v2/customers/
Retrieves the details of a customer from a specific source. Use embed
to other parameters to fetch specific details required.
Retrieves details of a specific customer such as:
- Profile information – first name, last name, registered date, registered at TILL
- Recent profile updated – details of the recent update in profile information
- Registered identifiers, communication channels
- Loyalty information – loyalty status, registered date, purchases, etc.
- Multiple Loyalty Program details: Program wise details if the org has multiple loyalty programs support
- Customer image
To fetch customer details from a specific account of a source (source with multiple accounts), you need to provide the respective account id.
If you attempt to retrieve data of any deleted customer after a successful PII deletion, you will receive the following response:
"message": "Customer is deleted after PII delete request"
API endpoint
{host}/v2//customers/{customerId}/{queryparameters}
Query parameters
Parameter (Parameters marked with * are mandatory) | Type | Description |
---|---|---|
source* | Enum [INSTORE, MARTJACK, WECHAT, LINE, ALL] | Specifies the source of the customer details to be retrieved. |
accountId | String | Unique identifier for the account. |
embed | Array of String | Details to include in the response. Supported values: points , subscriptions , mlp , userGroup , gapDetails , promotionalPoints , expirySchedules , expiredPoints , customerImage , returnedPoints , associatedImages , segments .Note: The associated images parameter retrieves the barcode image details associated with the customer. |
includedAllUserGroup2 | Boolean (false) | Pass true to see the customer details in all user groups. |
userGroup2Id | Long | Unique ID of the user group to fetch customer details from. |
includedUserGroup2LoyaltyDetails | Boolean (false) | Pass true to include loyalty details of user groups. |
includedFraudDetails | Boolean (false) | Pass true to include fraud details of the customer in the response. |
includedOnlyCurrentProfile | Boolean (false) | Pass true to fetch details of the current source and hide information from other sources. |
ug2JoinedStartDate | DateTime | Start date for filtering customers who joined user groups. |
ug2JoinedEndDate | DateTime | End date for filtering customers who joined user groups. |
ug2Offset | Integer | Specifies the offset for pagination of user group results. |
ug2Limit | Integer | Sets the maximum number of results to retrieve per page for user groups. |
ug2SortBy | String (JoinedDate) | Specifies the field by which the user group results should be sorted. |
ug2SortOrder | Enum [ASC, DESC] (DESC) | Specifies the sorting order for the user group results. |
ug2PaginationDetails | Boolean | Pass true to include pagination details for user groups. |
gapToUpgrade | Integer | Prerequisite: Set embed=MLP to retrieve the details.The gapToUpgrade parameter retrieves the details of the additional purchases, points, visits, or tracker value required for a customer to upgrade to the next tier. It calculates this based on a specified number of days from the current date.Supported values: 0: Retrieves the gap for the current day. 1: Calculates the gap for the next day. 30: Projects the gap 30 days from the current day. Negative values are not supported. |
gapToRenew | Integer | Prerequisite: Set embed=mlp to retrieve the details.Thie gapToRenew parameter retrieves the additional purchases, visits, points, or tracker value required for a customer to renew their tier after a specified number of days from the current date. Supported values::0: Retrieves the renewal value for the current day. 1: Calculates the renewal value for the next day. 30: Projects the renewal value 30 days from the current day. Negative values are not supported. Note: If the customer is in the base slab, this block will not be displayed. |
Response parameters
Parameter | Description |
---|---|
id | Unique identifier for the customer. |
profiles | List of customer profiles containing various details such as name, attribution, identifiers, communication channels, source, etc. |
loyaltyInfo | Information related to the customer's loyalty, including loyalty type, attribution, and lifetime purchases. |
segments | Object containing the segment and partition names. Example: "Activity segment": "Lapsed". Here, the Segment name is Activity segment, Partition value is Lapsed. Meaning: The customer is classified as "Lapsed" in the "Activity segment" category, indicating that they have not been active for a certain period. |
associatedWith | Code identifying the association of the customer (e.g., till code). |
ug2Pagination | Pagination details for user group results related to the customer. |
extendedFields | Additional extended fields associated with the customer, such as city and gender. |
cardDetails | Details of the card owned by the customer, including card ID, issued date, expiry date, series information, status, and more. |
warnings | List of warnings related to the response. |
upgradeStrategies | Provides the set of rules or conditions that defines how a customer progresses to a higher tier in a loyalty program. |
-upgrade_based_on | Parameter using which the upgrade condition is determined. Example: CUMULATIVE_PURCHASES ; TRACKER_VALUE_BASED , CURRENT_POINTS |
-upgradeThreshold | Threshold value required for an upgrade. Example: 25000 points. |
-customerUpgradeEntityValues | Current values related to the customer’s upgrade. |
--currentValue | Current value attained by the customer. Example: 9786 points. |
--gapToUpgrade | Additional value required for the upgrade. Example: 15214 points (threshold value - current value) |
--valueValidUpto | Date untill which the value is valid, in YYYY-MM-DD format. Example: 2025-05-06. |
gapToRenewSummary | Set of rules or conditions required for tier renewal for the customer in a loyalty program. Note: If the customer is in the base slab, this block will not be displayed. |
-tierExpiryDate | Expiry date of the current tier, in YYYY-MM-DD format. Example: 2024-12-31. |
-renewConfirmed | Indicates if the tier renewal is confirmed. Values: true or false . |
-renewStrategies | Array containing details of the rules or conditions for tier renewal. |
--renewBasedOn | Specifies the renewal strategy. Example: VISITS , PURCHASE , POINTS , or TRACKER . |
--trackerEntityIdentifiers | Array containing details of the tracker. Visible in case of tracker based renewal. |
---trackerName | Name of the tracker. Example: DowngradeTracker |
---trackerType | Entity tracked, such as transaction amount, line-item count, or customer visits. Example: LINEITEM_COUNT |
---trackerMode | Method used to evaluate tracker values over time, Example: MOVING_WINDOW , CYCLIC_WINDOW , CALENDAR_BASED_CYCLIC_WINDOW , or TIER_CHANGE_WINDOW . |
---trackerCaseName | Name of the specific tracker case. Example: Case1. |
---trackerCasePeriodType | Specifies the duration type for evaluating the tracker case, such as days, months, or calendar cycles. Example: DAYS |
---trackerCasePeriodValue | Value of the tracker case period. Example: 5 days. |
--renewThreshold | Threshold value required by the customer to renew the tier. Example: 5.0 for store visits, 10 for purchases. |
--customerRenewEntityValue | Current value reached by the customer. Example: 1 store visit or 123 points |
--customerGapToRenewValue | Additional value required for the tier renewal. Example: 4 store visits, 10 purchases or 1877 points. |