This API is used to retrieve the cart promotions tagged to a particular customer based on the user ID. This returns cart promotions issued to the customer or POS promotions which are tagged to the customer's tier or supplementary programs.
This API retrieves cart promotions and Point-of-Sale (POS) promotions specifically tagged to a customer based on their user ID. This includes cart promotions directly issued to the customer and POS promotions associated with the customer's loyalty tier or supplementary programs.
Note
The API returns POS promotions under the following conditions:
- Tier-Specific Promotions: If a promotion is configured for a specific loyalty tier (e.g., "Gold Tier") and the customer making the API call belongs to that tier, the promotion will be included in the response.
- Supplementary Program Promotions: When the includeSupplementaryPromotions parameter in the API call is set to true, promotions linked to supplementary programs will be returned.
The API will not return POS promotions in these scenarios:
- "All Loyalty Customers" Promotions: Promotions broadly applicable to all loyalty members, without being tied to a particular tier, are not returned by this API.
- No Tier or Supplementary Program Association: If a POS promotion is not explicitly linked to a customer tier or a supplementary program, it will not be part of the API's response.
Request Query Parameters
| Parameter | Data Type | Description |
|---|---|---|
| includeRedemptions | Boolean | includeRedemptions=true includes the restrictions applied to the promotion including max limit and remaining redemptions |
| includeSupplementaryPromotions | Boolean | includeSupplementaryPromotions=true includes the promotions tagged to the customer's supplementary program |
Response Parameters
Parameter | Data type | Description |
|---|---|---|
promotionId | String | Unique identifier of the Cart promotion |
promotionName | String | Name of the Cart promotion |
validTill | Long | Expiration timestamp (milliseconds since epoch) |
customerId | Long | Unique Identifier of the Customer using the Cart promotion |
earnedType | String | The method how cart promotion was earned. Supported values: NONE, TIER, REWARD, LOYALTY. None: Promotion is directly assigned to the customer, no qualification criteria required. Tier: Promotion is assigned based on the customers loyalty tier or status level, no qualifying action is required. Reward: Promotion is earned on the basis of completing a milestone or achievement, action is required. Loyalty: Promotion is tied to loyalty program. |
earnedStatus | String | Status of the earned cart promotion. Supported Values: LOCKED, UNLOCKED, EXPIRED. Locked: Promotion has been Issued but not yet available to use. Unlocked: Promotion is active and ready for the customer to use. Expired: Promotion was available before but cannot be used now. |
promotionStatus | String | Promotion can have three statues: ACTIVE, INACTIVE, EXPIRED.
|
milestoneId | Long | Milestone or achievement target linked to the promotion |
targetGroupId | Long | Identifier for a specific customer group eligible for the promotion based on predefined criteria. It indicates the offer was specifically designed for a customer segment. |
applicationMode | String | Indicates the way the promotion is applied. Supported Values: DISCOUNT, REWARD. Discount: Promotion applies to reduce the price, lowering the amount customer pays at checkout. Reward: It provides benefit or reward that does not applies at transaction. |
customFieldValues | Object | Contains custom key-value pairs related to the promotion |
restrictions | Object | Contains restrictions categorized by level. To view the restrictions, set |
| Array | Contains cart-level restrictions applicable to the promotion. |
| Array | Contains customer-level restrictions applicable to the promotion. |
| Array | Contains promotion-level restrictions applicable to the promotion. |
| Array | Contains product-level restrictions applicable to the promotion. Only |
| Array | Contains Product Category-level restrictions applicable to the promotion. Only |
-- kpi | String | Indicates the key performance metric used for restriction. |
-- maxLimit | String | Indicates the maximum allowed limit for a specific restriction. For Example, in a birthday cart promotion offer, if the |
-- remainingRedemption | String | Indicates the remaining number of times the cart promotion can be used by the customer. If the count is zero, it means that the promotion cannot be redeemed by the customer as they have already exhausted all the redemptions available. For example, in a birthday cart promotion offer with a maximum redemption limit of 1, if the customer has already redeemed the cart promotion, then even if promotionStatus is |
eventTime | Long | Timestamp of the event that triggered the cart promotion (milliseconds since epoch) |
supplementaryCriteria | Object | Defines additional loyalty based conditions. To get this response, set query parameter |
| Long | Identifier of the loyalty program associated with cart promotion |
| Enum | Indicates the type of program |
| Long | Indicates partner program Id, if it is a partner program |