This API retrieves the details of the specified promotion using the promotion ID and the corresponding program ID. It provides detailed information about the specific promotion including the type of promotion, its status, associated ruleset, program details, dates, limits, stacking, ranking, and restrictions.

By default, the types of promotions, ranking and stacking are not available for all the orgs. This needs to be enabled separately. For more details on the types of promotions, refer Types of promotions.

Types of promotions

There are three different types of promotions:

GENERIC (UI term - Available without issue)
LOYALTY (UI term - Direct issue)
LOYALTY_EARNING (UI term - Enrol & Issue)

The field pointsOfferType in the response provides information on the type of promotion.

Limits and restrictions

if the Types of promotions are enabled for your organisation, then the information regarding the limits and restrictions on issual, earning, or redemption is available in the objects promotionRestriction, object. This information is also replicated in the limits objects.

If your organisation does not have the Types of promotions enabled, the details on the limits and restrictions are only available in the limits object.

API endpoint example

<[https://eu.api.capillarytech.com/api_gateway/loyalty/v1/programs/469/promotions/57099/get>

Prerequisites

Authentication: Basic or OAuth authentication
Access group resource : Read access to customer group resource

Resource information


URI	/api_gateway/loyalty/v1/programs`\{programId\}`/promotions`\{promotionId\}`/get
HTTP method	GET
Pagination supported?	No
Rate limit	NA
Batch support	NA

Path parameters

Parameter	Datatype	Description
programId*	Long	Unique identifier of the loyalty program.
promotionId*	Long	Unique identifier of the loyalty promotion. Getting details of a loyalty promotion is currently supported by using the `promotionId`.

curl --location 'https://eu.api.capillarytech.com/api_gateway/loyalty/v1/programs/973/promotions/95085/get' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'Authorization: Basic *******' \
--header 'Cookie: _cfuvid=PalohBnIeOaJn_i7_SIjlvuMVIMKCKUXffaPvYTwUdU-1758871239198-0.0.1.1-604800000'

Response parameters

Parameter	Type	Description
status	Object	Contains status information for the response.
.code	Integer	Response code. Eample: 200
.message	String	Status message. Example: success
validationErrors	Object or null	Validation errors, if any.
data	Array of Objects	Contains promotion data.
.id	Integer	Unique identifier of the promotion.
.name	String	Name of the promotion.
.description	String	Description of the promotion.
.promotionStatus	String	Current status of the promotion. Example: COMPLETED, LIVE, PENDING, EXPIRED, UPCOMING
.lastUpdateDate	String (ISO 8601)	The date and time when the promotion was last updated.
.lastUpdatedBy	Integer	ID of the user who last updated the promotion.
.rulesetInfos	Array	Information about the ruleset associated with the promotion.
..id	Integer	Unique identifier for the ruleset.
..orgName	String	Organization name.
..contextID	Integer	Context ID of the ruleset.
..orgID	Integer	Organization ID.
..contextType	String	Type of context. Example: program
..rules	Array	Rules defined for the promotion.
...id	Integer	Unique identifier for the rule
...exp	String	Expression defining the rule.
...expJSON	String	Expression in JSON format.
...jsonType	String	JSON type of the expression.
...isActive	Boolean	Indicates if the rule is active.
...priority	Integer	Priority level of the rule.
...startDate	Long	Rule start date (epoch).
...endDate	Long	Rule end date (epoch).
...createdOn	Long	Rule creation timestamp (epoch).
...caseToActions	Object	Defines actions when rule evaluates to true.
....true	Array	Actions executed when the expression evaluates to true.
.....id	Integer	Action ID.
.....actionName	String	Name of the action.
.....actionClass	String	Java class implementing the action.
.....mandatoryPropertiesValues	Object	Key-value pairs of mandatory properties.
......(key-value pairs)	String/Integer	Specific property values (e.g., "PointType": "Main").
.....mandatoryComplexPropertiesValues	Object	Holds mandatory complex properties.
.....description	String	Description of the action.
...ruleScope	String	scope of the rule. Example: SERVER
...createdBy	Integer	ID of the user who created the rule.
...modifiedBy	Integer	ID of the user who last modified the rule.
...modifiedOn	Long	Last modified date (epoch).
...name	String	Rule name.
...description	String	Rule description.
...expDataType	String	Data type of the rule expression.
...filterInfo	Array	Filters applied to the rule.
...ruleSetId	Integer	ID of the ruleset to which the rule belongs.
...updatedViaNewUI	Boolean	Indicates whether the rule was updated via the new UI.
..ruleScope	String	Scope of the ruleset.
..startDate	Long	Ruleset start date (epoch).
..endDate	Long	Ruleset end date (epoch).
..createdOn	Long	Ruleset creation timestamp (epoch).
..createdBy	Integer	ID of ruleset creator.
..modifiedBy	Integer	ID of last user who modified the ruleset.
..modifiedOn	Long	Ruleset last modification timestamp.
..name	String	Ruleset name.
..packageName	String	Package name.
..description	String	Ruleset description.
..filterInfo	Array of Objects	Filters applied to the ruleset.
...id	Integer	Filter ID.
...orgID	Integer	Organization ID.
...ruleID	Integer	Associated rule ID.
...name	String	Filter name (e.g., "LoyaltyType", "EventSource").
...className	String	Java class name implementing the filter.
...isInclude	Boolean	Whether the filter includes or excludes matches.
...propertyToValues	Object	Key-value pairs defining filter property values.
....(key-value pairs)	Array of Strings	Values applied in the filter (e.g., "loyalty", "INSTORE").
..eventType	String or null	Event type (if applicable).
..cappingInfo	Array	Capping info for the ruleset.
..updatedViaNewUI	Boolean	Whether ruleset updated via new UI.
..label	String or null	Ruleset label.
..private	Boolean	Whether ruleset is private.
.programName	String	Program name.
.programId	Integer	Program identifier.
.startDate	String (ISO 8601)	Promotion start date.
.endDate	String (ISO 8601)	Promotion end date.
.identifier	String	Promotion unique identifier.
.isActive	Boolean	Indicates if promotion is active.
.eventName	String	Event name triggering the promotion.
.allocatePointsOn	String	Defines when points are allocated. Example: BILL
.limits	Object	Defines limits of the promotion.
..pointsPerCustomer	Integer	Maximum points a customer can earn.
..numberOfTimesPerCustomer	Integer	Maximum number of activities per customer that can allocate points.
..totalPointsInPromotion	Integer	Maximum points permitted across customers within the promotion duration.
..totalPointsPerEventLimit	Integer	Limit on the total points that can be earned per event within the promotion.
.useProportions	Boolean	Indicates whether proportions are used for the promotion.
.pointsOfferType	String	Type of promotion. Example: GENERIC/LOYALTY/LOYALTY_EARNING
.promotionRestrictions	Object	Restrictions and settings for the promotion. Issual restrictions - Provides info on the restrictions on the enrolment of the customers. earnRestrictions provides information on the restrictions on the promotion issual. expiryRestrictions provide info on the enrol and issue expiry. Redemption restrictions provides information on the maximum redemptions of points per issue of promotion
..restrictions	String	Restriction details.
..scope	String	Scope of restrictions.
..loyaltyEarningType	Enum	Mode of loyalty earning for the promotion. Values: ISSUE_AND_EARN, DIRECT_EARN
..expiryReminder	String	Notification config for reminding customers before promotion/earn expiry.
..targetGroupIds	Array	Target group identifiers
..targetRuleIds	Array	Target rule identifiers
..linkedTargetGroupVsTargetRuleIdMap	Object	Canonical mapping of target group ID to a list of target rule IDs
..cappingStatus	String	Status flag indicating whether capping is active/considered for the promotion scope.
..skipEarnedDateCheckOnRedeem	Boolean	Indicates whether to skip the earned date check during redemption. If `true`, the system bypasses the earned date check during redemption validations.
..isStackable	Boolean	Indicates whether promotion can be stacked.
..isConsideredForRanking	Boolean	Indicates whether the promotion participates in ranking strategies.
..isExclusive	Boolean	Indicates whether promotion is exclusive. If `true`, users cannot combine this promotion with other promotions during application.
..isAlwaysApply	Boolean	Indicates whether promotion always applies. If `true`, always apply promotion when eligible, irrespective of ranking/strategy conflicts.

Example response

{
    "status": {
        "code": 200,
        "message": "success"
    },
    "validationErrors": null,
    "data": [
        {
            "id": 95085,
            "name": "AllRewards",
            "description": "",
            "promotionStatus": "COMPLETED",
            "lastUpdateDate": "2025-06-23T08:02:58Z",
            "lastUpdatedBy": 75155288,
            "rulesetInfos": [
                {
                    "id": 126408744,
                    "orgName": "DocDemo",
                    "contextID": 973,
                    "orgID": 100737,
                    "contextType": "program",
                    "rules": [
                        {
                            "id": 126595178,
                            "exp": "true",
                            "expJSON": "\n{\n  \"arity\":\"literal\",\n  \"value\":\"true\",\n  \"type\":\"boolean:primitive\"\n}",
                            "jsonType": "JNODE",
                            "isActive": true,
                            "priority": -1,
                            "startDate": 1118300462375,
                            "endDate": 2064985262375,
                            "createdOn": 1749452462375,
                            "caseToActions": {
                                "true": [
                                    {
                                        "id": 126771365,
                                        "actionName": "AWARD_POINTS_ACTION",
                                        "actionClass": "com.capillary.shopbook.pointsengine.endpoint.impl.action.AwardPointsActionImpl",
                                        "mandatoryPropertiesValues": {
                                            "ProRateOnSourceValue": "EVENT_DEFAULT_VALUE",
                                            "DelayStrategy": "AS_DEFINED_IN_ALLOCATION_STRATEGY",
                                            "SourceValueRoundingStrategy": "ACTUAL",
                                            "EvaluatedEntity": "USER",
                                            "ExpiryStrategy": "11833",
                                            "PointType": "Main",
                                            "AwardStrategy": "11879",
                                            "DelayExtendedFieldName": "",
                                            "PointsRoundingStrategy": "ACTUAL"
                                        },
                                        "mandatoryComplexPropertiesValues": {},
                                        "description": "2X"
                                    },
                                    {
                                        "id": 126771366,
                                        "actionName": "CONVERT_POINTS_TO_REWARD_ACTION",
                                        "actionClass": "com.capillary.shopbook.pointsengine.endpoint.impl.action.RewardIssualActionImpl",
                                        "mandatoryPropertiesValues": {
                                            "quantityBasedOn": "POINTS_ON_EVENT",
                                            "brandName": "DOCDEMO",
                                            "rewardId": "295948",
                                            "brandId": "61",
                                            "quantityValue": "",
                                            "isRewardIssualForCustomerActivity": "true",
                                            "fulfillmentStatus": "ON ITS WAY"
                                        },
                                        "mandatoryComplexPropertiesValues": {},
                                        "description": "Convert points to reward action"
                                    },
                                    {
                                        "id": 126771367,
                                        "actionName": "BADGE_EARN_ACTION",
                                        "actionClass": "com.capillary.shopbook.pointsengine.endpoint.impl.action.BadgeEarnActionImpl",
                                        "mandatoryPropertiesValues": {
                                            "ownerType": "Loyalty_Promotion",
                                            "badgeMetaId": "67eb99516666db076c3c7519",
                                            "badgeMetaName": "Badge Issue georgetest",
                                            "referenceId": "973_TransactionAdd_c143a683"
                                        },
                                        "mandatoryComplexPropertiesValues": {},
                                        "description": "Badge Issue georgetest"
                                    },
                                    {
                                        "id": 126771368,
                                        "actionName": "ISSUE_ALTERNATE_CURRENCY_9DxGBP",
                                        "actionClass": "com.capillary.shopbook.pointsengine.endpoint.impl.action.BillAwardPointsActionImpl",
                                        "mandatoryPropertiesValues": {
                                            "ProRateOnSourceValue": "EVENT_DEFAULT_VALUE",
                                            "DelayStrategy": "AS_DEFINED_IN_ALLOCATION_STRATEGY",
                                            "SourceValueRoundingStrategy": "ACTUAL",
                                            "EvaluatedEntity": "USER",
                                            "AlternateCurrencyIdentifier": "9DxGBP",
                                            "ZeroAwardStrategy": "11879",
                                            "ExpiryStrategy": "11833",
                                            "PointType": "REGULAR",
                                            "AwardStrategy": "11879",
                                            "DelayExtendedFieldName": "",
                                            "PointsRoundingStrategy": "ACTUAL"
                                        },
                                        "mandatoryComplexPropertiesValues": {},
                                        "description": "2X"
                                    }
                                ]
                            },
                            "ruleScope": "SERVER",
                            "createdBy": 60594279,
                            "modifiedBy": 60594279,
                            "modifiedOn": 1749452462375,
                            "name": "Rule 1",
                            "description": "",
                            "expDataType": null,
                            "filterInfo": [],
                            "ruleSetId": 126408744,
                            "updatedViaNewUI": false
                        }
                    ],
                    "ruleScope": "SERVER",
                    "startDate": 1749427200000,
                    "endDate": 1751327999000,
                    "createdOn": 1749452462375,
                    "createdBy": 60594279,
                    "modifiedBy": 60594279,
                    "modifiedOn": 1749452462375,
                    "name": "ruleset_20250609070102",
                    "packageName": "",
                    "description": "",
                    "filterInfo": [
                        {
                            "id": 126644898,
                            "orgID": 100737,
                            "ruleID": -1,
                            "name": "LoyaltyType",
                            "className": "com.capillary.shopbook.emf.impl.filter.LoyaltyTypeFilterImpl",
                            "isInclude": true,
                            "propertyToValues": {
                                "loyaltyType": [
                                    "loyalty"
                                ]
                            }
                        },
                        {
                            "id": 126644899,
                            "orgID": 100737,
                            "ruleID": -1,
                            "name": "EventSource",
                            "className": "com.capillary.shopbook.emf.impl.filter.EventSourceFilterImpl",
                            "isInclude": true,
                            "propertyToValues": {
                                "eventSource": [
                                    "INSTORE"
                                ]
                            }
                        }
                    ],
                    "eventType": null,
                    "cappingInfo": [],
                    "updatedViaNewUI": false,
                    "label": null,
                    "private": false
                }
            ],
            "programName": "DocDemoDefaultProgram",
            "programId": 973,
            "startDate": "2025-06-09T00:00Z",
            "endDate": "2025-06-30T23:59:59Z",
            "identifier": "0b89574e-aab9-49ad-812f-c1ea709f5daf",
            "isActive": true,
            "eventName": "TRANSACTIONADD",
            "allocatePointsOn": "BILL",
            "limits": {
                "pointsPerCustomer": 0,
                "numberOfTimesPerCustomer": 0,
                "totalPointsInPromotion": 0,
                "totalPointsPerEventLimit": 0
            },
            "useProportions": false,
            "pointsOfferType": "GENERIC",
            "promotionRestrictions": {
                "restrictions": null,
                "scope": null,
                "loyaltyEarningType": null,
                "expiryReminder": null,
                "targetGroupIds": null,
                "targetRuleIds": null,
                "linkedTargetGroupVsTargetRuleIdMap": null,
                "cappingStatus": null,
                "skipEarnedDateCheckOnRedeem": false,
                "isStackable": false,
                "isConsideredForRanking": false,
                "isExclusive": false,
                "isAlwaysApply": false
            }
        }
    ]
}

API-specific error codes

Error code	Description
4029	Promotion ID is invalid.
2010	Program ID is invalid.