Get Cart Promotions available for a Customer

get https://{host}/api_gateway/v1/promotions/customer/109943742?includeRedemptions=true&includeSupplementaryPromotions=true

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.

📘
Notes
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.

Example request

curl --location 'https://{Host}/api_gateway/v1/promotions/customer/566881933?includeRedemptions=true&isIncludeActivePromotionsOnly=true' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTNhGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=uvNcgoyX0Q6nkA64njE4pSA_tJw1wkWo-1762160764633-0.0.1.1-604800000'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Resource information


Pagination	No
Batch support	No

Rate limit

Demo and Testing Clusters: 1,000 requests per minute per API key
Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Path parameters

Field	Type	Required	Description
customerId	Number	Yes	Unique identifier for the customer.

Query parameters

Field	Type	Required	Description
includeRedemptions	Boolean	Optional	If true, includes the restrictions applied to the cart promotion, such as maxLimit and remainingRedemption.
includeSupplementaryPromotions	Boolean	Optional	If true, includes POS cart promotions tagged to the customer's supplementary programs.
isIncludeActivePromotionsOnly	Boolean	Optional	If true, returns only cart promotions that are currently active.

Example response

{
    "data": [
        {
            "earnedPromotionId": "68df4539dd46cd232fb6fbd3",
            "promotionId": "68df4516f398ae3dc88031df",
            "promotionName": "cart_based test jo",
            "validTill": 1790985600000,
            "validTillISO": "2026-10-03T00:00:00Z",
            "unlockedDate": 1759462713920,
            "unlockedDateISO": "2025-10-03T03:38:33Z",
            "customerId": 566881933,
            "earnedType": "NONE",
            "earnedStatus": "UNLOCKED",
            "promotionStatus": "INACTIVE",
            "applicationMode": "DISCOUNT",
            "redeemableFrom": 1759462713920,
            "redeemableFromISO": "2025-10-03T03:38:33Z",
            "customFieldValues": {
                "Age": "25"
            },
            "eventTime": 1759462713920,
            "eventTimeISO": "2025-10-03T03:38:33Z"
        }
    ],
    "errors": []
}

Response parameters

Field	Type	Description
data	Array	Defines a list of cart promotion objects available to the customer.
.earnedPromotionId	String	Specifies the unique identifier for the instance of the earned cart promotion.
.promotionId	String	Specifies the unique identifier of the base Cart promotion.
.promotionName	String	Specifies the name of the Cart promotion.
.validTill	Long	Indicates the expiration timestamp in milliseconds since epoch.
.validTillISO	String	Indicates the expiration in UTC. Time format: ISO 8601 format.
.unlockedDate	Long	Indicates the timestamp when the cart promotion became available (unlocked) for use, in UTC. Time format: milliseconds since epoch.
.unlockedDateISO	String	Indicates the timestamp when the cart promotion became available in UTC. Time format: ISO 8601 format.
.customerId	Long	Specifies the Unique Identifier of the Customer using the Cart promotion.
.earnedType	String	Specifies the method how cart cart promotion was earned.
.earnedStatus	String	Specifies the status of the earned cart promotion.
.promotionStatus	String	Specifies the overall status of the cart promotion.
.milestoneId	Long	Specifies the milestone or achievement target linked to the cart promotion.
.targetGroupId	Long	Specifies the identifier for a specific customer group eligible for the cart promotion.
.applicationMode	String	Indicates the way the cart promotion is applied.
.redeemableFrom	Long	Indicates the timestamp from when the cart promotion is redeemable, in UTC. Time format: milliseconds since epoch.
.redeemableFromISO	String	Indicates the timestamp from when the cart promotion is redeemable, in UTC. Time format ISO 8601 format.
.customFieldValues	Object	Defines an object containing custom key-value pairs related to the cart promotion.
.eventTime	Long	Indicates the timestamp of the event that triggered the cart promotion, in UTC. Time format: milliseconds since epoch.
.eventTimeISO	String	Indicates the timestamp of the event in UTC. Time format: ISO 8601 format.
.restrictions	Object	Defines an object containing restrictions categorized by level. Indicates this is returned if includeRedemptions=true.
..Cart	Array	Defines an array of cart-level restrictions.
..Customer	Array	Defines an array of customer-level restrictions.
..Promotion	Array	Defines an array of cart promotion-level restrictions.
..Product	Array	Defines an array of product-level restrictions.
..Category	Array	Defines an array of category-level restrictions.
...kpi	String	Indicates the key metric used for restriction.
...maxLimit	String	Indicates the maximum allowed limit for the restriction.
...remainingRedemption	String	Indicates the remaining number of times the cart promotion can be used.
.supplementaryCriteria	Object	Defines additional loyalty-based conditions. Indicates this is returned if includeSupplementary Promotions is set to `true`.
..loyaltyprogramId	Long	Specifies the identifier of the associated loyalty program.
..programType	Enum	Indicates the type of program.
..partnerprogramId	Long	Indicates the partner program ID.
errors	Array	Defines a list of error objects, which is empty on success.

Error codes

HTTP code	Description
400	Invalid request. Check required path or query parameters.
401	Authentication failed. Check your API key or credentials.
404	Customer not found. The specified customerId does not exist.

Language

Credentials

Basic

base64

URL

Click Try It! to start a request and see the response here!