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. |
Note:
Retrieving Customers transaction data in bulk is NOT supported in this API.
API specific Error Code
| Error Code | Description | Reason |
|---|---|---|
| 400 | Bad Request with Blank response | Not passed valid identifiers |