Time	Status	User Agent
Retrieving recent requests…

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.

Result limit and sort order:

The API returns a maximum of 10 promotions by default, sorted by expiry date (latest first). Use the limit query parameter to override this default.

The API response does not include pagination metadata such as limit or skip. To retrieve promotions beyond the default limit, pass a higher value using the limit parameter.

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'

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

curl --location 'https://{Host}/api_gateway/v1/promotions/customer/566881933?includeRedemptions=true&isIncludeActivePromotionsOnly=true&includeSupplementaryPromotions=true&limit=20' \
--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

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. Supplementary promotions with later expiry dates are sorted to the top of the result set, which will cause other promotions to be omitted from the response when the result limit is reached.
isIncludeActivePromotionsOnly	Boolean	Optional	If true, returns only cart promotions that are currently active.
entityId	Long	Optional	Filters the response to promotions associated with the specified entity. The entity ID is resolved against the org hierarchy, passing a ZONE, TILL, STORE or ID, which includes all promotions mapped to entities within that hierarchy. Promotions not mapped to any till or store are always included, regardless of the value passed. If omitted, no store-based filtering is applied.
limit	Integer	Optional	Specifies the maximum number of promotions to return. Defaults to 10 if not provided.

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 timestamp of the cart promotion in ISO 8601 format, returned in the server time zone. EU server example 2026-10-03T00:00:00Z → 03 October 2026, 00:00:00 (UTC) India server example 2026-10-03T05:30:00+05:30 → 03 October 2026, 05:30:00 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
.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 in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:12:45Z → 04 February 2026, 09:12:45 (UTC) India server example 2026-02-04T14:42:45+05:30 → 04 February 2026, 14:42:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
.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 in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:14:10Z → 04 February 2026, 09:14:10 (UTC) India server example 2026-02-04T14:44:10+05:30 → 04 February 2026, 14:44:10 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
.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 in ISO 8601 format, returned in the server time zone. EU server example 2026-02-04T09:11:58Z → 04 February 2026, 09:11:58 (UTC) India server example 2026-02-04T14:41:58+05:30 → 04 February 2026, 14:41:58 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
.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.
...windowType	Enum	Indicates the type of limit window applied to this restriction.
...fixedWindowConfig	Object	Indicates the cycle configuration for the restriction when `windowType` is `FIXED`.
....cycleType	Enum	Indicates the type of fixed cycle.
....weekStartDay	Enum	Indicates the start day of the weekly cycle when `cycleType` is `WEEK`.
....refreshRate	Integer	Indicates the number of days per cycle when `cycleType` is `N_DAY`.
....cycleReferenceDate	Long	Epoch timestamp in milliseconds. The anchor date from which N_DAY cycles are calculated. Interpreted in the org's configured timezone.
...currentCycle	Object	Indicates the active cycle window at the time of the API call. Only present when `windowType` is `FIXED`.
....startDate	Long	Epoch timestamp in milliseconds. Inclusive start of the current cycle window.
....endDate	Long	Epoch timestamp in milliseconds. Inclusive end of the current cycle window.
...periodStart	Long	Epoch timestamp in milliseconds. Same as `currentCycle.startDate`; used for display and UI rendering. Returns `null` for `OVERALL` restrictions.
...periodEnd	Long	Epoch timestamp in milliseconds. Same as `currentCycle.endDate`; used for display and UI rendering. Returns `null` for `OVERALL` restrictions.
.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.