Retrieves a paginated list of promotions for a given program. You can filter the promotions based on source type, event name etc.

By default, the types of promotions 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.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/loyalty/v1/programs/973/promotionsV2?limit=100&offset=0&sourceType=USER_CREATED' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic **********' \
--header 'Cookie: _cfuvid=ZkF.LSNXg9S52IfnjuqAXPBT0mhsN4NBGQOun0VO.bo-1758631730852-0.0.1.1-604800000'

Prerequisites

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

Resource information


URI	/api_gateway/loyalty/v1/programs/`{programId}`/promotionsV2
HTTP Method	GET
Pagination	Yes
Batch support	No

Path parameters

Parameter Name	Data Type	Description
programId	String	Unique ID of the program

Query parameters

Parameter Name	Data Type	Description
`limit*`	String	Number of results that need to be displayed. The values from zero to a maximum of 100 are supported.
`sourceType*`	ENUM	Filter promotion data based on its source type. Possible values are `UI`, `IMPORT`, `GOODWILL`, `CAMPAIGN`, `POINTS_TRANSFER`, `IMPORT_API`, `PROMOTION_API`, `POINTS_CONTRIBUTION_TO_GROUP`,`MANUAL_POINTS_ADJUSTMENT`, `BADGES`, `USER_CREATED` <br/><br/> Use the filter `USER_CREATED` to filter the promotions created for User Created Challenges (UCC)
`offset*`	String	Start index for data retrieval. This value should not be negative.
`promotionId`	Integer	The unique ID of the promotion.
`includeInactivePromotions`	Boolean	Include promotions that are currently inactive.<br/>By default this is set to false.
`startRuleIdentifier`	Integer	The unique identifier of the start rule.
`eventName`	String	Set the event name to filter based on an event.

Response body

{
    "status": {
        "code": 200,
        "message": "success"
    },
    "validationErrors": null,
    "data": [
        {
            "id": 96664,
            "name": "test_promo_uniqueName110",
            "description": "creating promotion via API",
            "promotionStatus": "LIVE",
            "lastUpdateDate": "2025-06-23T09:25:04Z",
            "lastUpdatedBy": -1,
            "rulesetInfos": [
                {
                    "id": 126412694,
                    "orgName": "DocDemo",
                    "contextID": 2932,
                    "orgID": 100737,
                    "contextType": "program",
                    "rules": [
                        {
                            "id": 126600796,
                            "exp": "true",
                            "expJSON": "{ \"arity\": \"literal\", \"value\": \"true\", \"type\": \"boolean:primitive\" }",
                            "jsonType": "JNODE",
                            "isActive": true,
                            "priority": -1,
                            "startDate": 1089532593324,
                            "endDate": 33593126193324,
                            "createdOn": 1750670704532,
                            "caseToActions": {
                                "true": [
                                    {
                                        "id": 126778453,
                                        "actionName": "AWARD_TARGET_POINTS_ACTION",
                                        "actionClass": "com.capillary.shopbook.pointsengine.endpoint.impl.action.AwardTargetPointsActionImpl",
                                        "mandatoryPropertiesValues": {
                                            "TargetRuleId": "123",
                                            "ProRateOnSourceValue": "EVENT_DEFAULT_VALUE",
                                            "DelayStrategy": "AS_DEFINED_IN_ALLOCATION_STRATEGY",
                                            "SourceValueRoundingStrategy": "ACTUAL",
                                            "TargetGroupId": "1234567",
                                            "ExpiryStrategy": "81042",
                                            "TargetRuleName": "TargetRuleName",
                                            "AwardStrategy": "82690",
                                            "PointsRoundingStrategy": "ACTUAL"
                                        },
                                        "mandatoryComplexPropertiesValues": {},
                                        "description": null
                                    }
                                ]
                            },
                            "ruleScope": "SERVER",
                            "createdBy": -1,
                            "modifiedBy": -1,
                            "modifiedOn": 1750670704532,
                            "name": "Rule 1",
                            "description": "Rule 1",
                            "expDataType": null,
                            "filterInfo": [],
                            "ruleSetId": 126412694,
                            "updatedViaNewUI": false
                        }
                    ],
                    "ruleScope": "SERVER",
                    "startDate": 1089532593324,
                    "endDate": 33593126193324,
                    "createdOn": 1750670704532,
                    "createdBy": -1,
                    "modifiedBy": -1,
                    "modifiedOn": 1750670704532,
                    "name": "rulesetName_uniqueue1",
                    "packageName": "",
                    "description": "Promotional Rulesets",
                    "filterInfo": [
                        {
                            "id": 126654282,
                            "orgID": 100737,
                            "ruleID": -1,
                            "name": "LoyaltyType",
                            "className": "com.capillary.shopbook.emf.impl.filter.LoyaltyTypeFilterImpl",
                            "isInclude": true,
                            "propertyToValues": {
                                "loyaltyType": [
                                    "loyalty"
                                ]
                            }
                        },
                        {
                            "id": 126654283,
                            "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": "userCreatedLabel_2025-06-23T09:25:04.532Z",
                    "private": true
                }
            ],
            "programName": "DocDemoDefaultProgram",
            "programId": 973,
            "startDate": "2025-06-23T00:00Z",
            "endDate": "2026-08-25T23:59:59Z",
            "identifier": "test_promo_uniqueIdentifier110",
            "isActive": true,
            "eventName": "TARGETCOMPLETED",
            "allocatePointsOn": "BILL",
            "limits": {
                "pointsPerCustomer": 10,
                "numberOfTimesPerCustomer": 2,
                "totalPointsInPromotion": 10,
                "totalPointsPerEventLimit": -1
            },
            "useProportions": false,
            "pointsOfferType": "LOYALTY",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_ALLOWED_TIMES_PER_CUSTOMER",
                            "value": 3,
                            "type": "PERIOD_BASED",
                            "periodType": "MOVING_WINDOW",
                            "periodUnit": "WEEKLY"
                        },
                        {
                            "name": "MAX_ALLOWED_TIMES_PER_PROMOTION",
                            "value": 3,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        },
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [
                        {
                            "name": "MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER",
                            "value": 3
                        }
                    ],
                    "earnRestrictions": [
                        {
                            "name": "MAX_NUMBER_OF_EARNS_PER_CUSTOMER",
                            "value": 3
                        }
                    ],
                    "expiryRestrictions": [
                        {
                            "name": "ISSUAL_PROMOTION_EXPIRY_BASED_ON",
                            "value": 10,
                            "type": "PROMOTION"
                        }
                    ]
                },
                "scope": null,
                "loyaltyEarningType": "ISSUE_AND_EARN",
                "expiryReminder": null,
                "targetGroupIds": [
                    1234567
                ],
                "targetRuleIds": [
                    123
                ],
                "linkedTargetGroupVsTargetRuleIdMap": {
                    "1234567": [
                        123
                    ]
                },
                "cappingStatus": null,
                "skipEarnedDateCheckOnRedeem": false,
                "isStackable": false,
                "isConsideredForRanking": false,
                "isExclusive": false,
                "isAlwaysApply": false
            }
        }
    ],
    "pageDetails": {
        "pageNumber": 0,
        "pageSize": 100,
        "totalEntries": 1,
        "pageCount": 1
    }
}

Response parameters

Field	Data Type	Description
`status`	Object	Contains the status of the API response.
• `code`	Integer	HTTP status code.
• `message`	String	Describes the result of the request (e.g., "success").
`validationErrors`	Object or null	If validation fails, errors are displayed here.
`data`	Array of Objects	Contains promotion data.
• `id`	Integer	The unique identifier for the promotion.
• `name`	String	The name of the promotion.
• `description`	String	Description of the promotion.
• `promotionStatus`	String	The current status of the promotion (e.g., "LIVE").
• `lastUpdateDate`	String (ISO 8601)	Timestamp of the last update made to the promotion.
• `lastUpdatedBy`	Integer	ID of the user who last updated the promotion.
• `rulesetInfos`	Array of Objects	A list of rulesets associated with the promotion.
• `id`	Integer	The unique identifier for the ruleset.
• `orgName`	String	Name of the organization to which the ruleset belongs.
• `contextID`	Integer	Context ID in which the ruleset applies (e.g., program).
• `orgID`	Integer	Organization ID to which the ruleset belongs.
• `contextType`	String	The type of context the ruleset belongs to (e.g., "program").
• `rules`	Array of Objects	A list of rules within the ruleset.
• `id`	Integer	Unique identifier for the rule.
• `exp`	String	Expression used by the rule.
• `expJSON`	String	JSON representation of the rule expression.
• `jsonType`	String	The JSON node type used in the rule.
• `isActive`	Boolean	Indicates if the rule is active.
• `priority`	Integer	Priority level of the rule (lower numbers indicate higher priority).
• `startDate`	Long	Start date of the rule in epoch time.
• `endDate`	Long	End date of the rule in epoch time.
• `createdOn`	Long	Date the rule was created, in epoch time.
• `caseToActions`	Object	Actions tied to the rule when certain conditions are met (in this case, `"true"`).
• `true`	Array of Objects	Actions to be executed when the expression evaluates to true.
• `id`	Integer	ID of the action to be executed.
• `actionName`	String	Name of the action (e.g., "AWARD_TARGET_POINTS_ACTION").
• `actionClass`	String	Java class that implements the action.
• `mandatoryPropertiesValues`	Object	Key-value pairs defining mandatory properties for the action.
• `(key-value pairs)`	Varies (String, Integer)	Specific mandatory properties and their values.
• `mandatoryComplexPropertiesValues`	Object	Holds any mandatory complex properties for the action (if applicable).
• `description`	String or null	Description of the action (if applicable).
• `ruleScope`	String	Scope of the rule (e.g., "SERVER").
• `createdBy`	Integer	ID of the user who created the rule.
• `modifiedBy`	Integer	ID of the user who last modified the rule.
• `modifiedOn`	Long	Date the rule was last modified, in epoch time.
• `name`	String	Name of the rule.
• `description`	String	Description of the rule.
• `ruleSetId`	Integer	ID of the ruleset to which the rule belongs.
• `updatedViaNewUI`	Boolean	Indicates if the rule was updated via the new UI.
• `ruleScope`	String	Scope of the ruleset
• `startDate`	String	Ruleset start date in epoch milliseconds
• `endDate`	String	Ruleset end date in epoch milliseconds
• `createdOn`	Long	Date the rule was created, in epoch time.
• `createdBy`	Integer	ID of the user who created the ruleset.
• `modifiedBy`	Integer	ID of the user who last modified the rule.
• `modifiedOn`	Long	Date the rule was last modified, in epoch time.
• `name`	String	Name of the ruleset
• `packageName`	String	Package name for the ruleset
• `description`	String	Description of ruleset
• `filterInfo`	Array	List of filters applied to the ruleset.
• `id`	Integer	Unique identifier of the filter.
• `orgID`	Integer	Organization ID linked to the filter.
• `ruleID`	Integer	Rule ID associated with the filter.
• `name`	String	Name of the filter. Example: LoyaltyType, EventSource
• `className`	String	Java class name that implements the filter.
• `isInclude`	Boolean	Indicates whether the filter: -`true` : Includes entities that match the property values defined in `propertyToValues`. -`false` : Excludes entities that match the property values defined in `propertyToValues`.
• `propertyToValues`	Object	Key-to-list mapping of filter properties.
• `eventType`	String	Event type associated with ruleset
• `cappingInfo`	Array	Array containing information on the capping or limits of the ruleset.
• `updatedViaNewUI`	Boolean	Indicates if the rule was updated via the new UI.
• `label`	String	Label of the ruleset
• `private`	Boolean	Ruleset privacy flag
• `programName`	String	Name of the program associated with the promotion.
• `programId`	Integer	Unique identifier for the program.
• `startDate`	String (ISO 8601)	Start date of the promotion in ISO format.
• `endDate`	String (ISO 8601)	End date of the promotion in ISO format.
• `identifier`	String	A unique identifier for the promotion.
• `isActive`	Boolean	Indicates if the promotion is active.
• `eventName`	String	The name of the event that triggers the promotion (e.g., "TARGETCOMPLETED").
• `allocatePointsOn`	String	Defines when points should be allocated (e.g., "BILL").
• `limits`	Object	Defines various limits related to the promotion.
• `pointsPerCustomer`	Integer	Limit on the number of points a customer can earn through this promotion (-1 indicates no limit).
• `numberOfTimesPerCustomer`	Integer	Limit on the number of times a customer can participate in the promotion (-1 indicates no limit).
• `totalPointsInPromotion`	Integer	Total number of points that can be awarded in this promotion (-1 indicates no limit).
• `totalPointsPerEventLimit`	Integer	Limit on the number of points that can be earned per event (-1 indicates no limit).
• `useProportions`	Boolean	Indicates if points should be allocated based on proportions.
• `pointsOfferType`	String	Type of points offer (e.g., "LOYALTY").
• `promotionRestrictions`	Object	Defines restrictions for the promotion.
• `restrictions`	Object	Object of redemption restrictions.
• `redemptionRestrictions`	Object	Contains information on the redemption limits for a promotion.
• `name`	Enum	Type of redemption restriction. Possible values:<br/>`MAX_ALLOWED_POINTS_PER_EVENT`: The maximum points that can be earned for a single activity (make a transaction, redeem points etc.) done by a customer.<br/>`MAX_ALLOWED_TIMES_PER_CUSTOMER`: The maximum number of activities (make a transaction, redeem points etc.) a customer can do to earn points.<br/>`MAX_ALLOWED_POINTS_PER_CUSTOMER`:The maximum number of points a customer can earn from a promotion.<br/>`MAX_ALLOWED_TIMES_PER_PROMOTION`: The maximum number of activities (make a transaction, redeem points etc.) allowed across all customers in the brand for the promotion.<br/>`MAX_ALLOWED_POINTS_PER_PROMOTION`:The maximum number of points available across all customers in the brand for the promotion.<br/>`MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER`:The maximum number of times a customer can redeem a promotion after earning
• `value`	Integer	Number of units corresponding to the `name`. Specify `-1` for no limit (max limit: 100).
• `type`	Enum	Type of period for restriction. Possible values: `PERIOD_BASED`, `NON_PERIOD_BASED`.
• `periodType`	Enum	Type of period. Supported value: `MOVING_WINDOW`.
• `periodUnit`	Enum	Frequency of the period. Possible values: `DAILY`, `WEEKLY`, `MONTHLY`.
• `issualRestrictions`	Object	Contains information on the issual limits for a promotion.
• `name`	Enum	Type of issual restriction. Possible values:<br/>`MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER`: Maximum number of times a promotion can be issued to a customer.
• `value`	Integer	Number of units corresponding to the `name`. Specify `-1` for no limit (max limit: 100).
• `earnRestrictions`	Object	Contains information on the earn limits for a promotion (specific to enrol-and-issue promotions).
• `name`	Enum	Type of earn restriction. Possible values:<br/>`MAX_NUMBER_OF_EARNS_PER_CUSTOMER`: The maximum number of times a loyalty promotion can be issued to a customer.<br/>`MAX_NUMBER_OF_EARNS_PER_PROMOTION`: The maximum number of times a loyalty promotion can be issued across customers.<br/>`MAX_POINTS_PER_EARN_PER_CUSTOMER`: The maximum number of points a customer can earn in a single event from a promotion.
• `value`	Integer	Number of units corresponding to the `name`. Specify `-1` for no limit (max limit: 100).
• `expiryRestrictions`	Object	Contains information on the expiry for a promotion (mandatory for all promotion types).
• `name`	Enum	Action that is expiring. Possible values:<br/>`ISSUAL_PROMOTION_EXPIRY_BASED_ON`: The time period within which the customer must complete the activity required to issue the loyalty promotion. Once this lapses, the customer cannot earn the loyalty promotion.<br/>`EARN_PROMOTION_EXPIRY_BASED_ON`: The time period within which the customer must complete the activity required to receive the loyalty promotion benefits. Once this lapses, the customer cannot earn the benefits.
• `type`	Enum	Type of expiration. Possible values: `PROMOTION`, `CUSTOM`.
• `value`	Integer	Number of days the loyalty promotion expires from the date of issual.
`scope`	Object or null	Scope of the promotion restrictions.
`isStackable`	Boolean	Defines if this promotion can be stacked with other promotions.
`isConsideredForRanking`	Boolean	Indicates if this promotion should be considered for ranking purposes.
`loyaltyEarningType`	String	Defines the type of loyalty earning (e.g., "ISSUE_AND_EARN").
`expiryReminder`	String	Configuration for sending reminders before earned/issued benefits expire.
`isExclusive`	Boolean	Defines if the promotion is exclusive.
`isAlwaysApply`	Boolean	Indicates if the promotion should always be applied.
`targetGroupIds`	Array of Integers	A list of target group IDs associated with the promotion.
`linkedTargetGroupVsTargetRuleIdMap`	Object	Object containing the mapping between target group IDs and their associated target rule IDs
`cappingStatus`	String	Status of the capping configuration. Values: ACTIVE, INACTIVE, or `null` if no capping is configured. ACTIVE: The defined capping limits/filters are enforced during evaluation/redemption INACTIVE/null - capping is not applied.
`skipEarnedDateCheckOnRedeem`	Boolean	Determines whether redemption must occur within the validity window for the earned promotion. false (default): Enforces date checks during redemption. The event date must be between the `createdOn` and `expiresOn` dates of the earn. true: Skips the earned date window check during redemption; redemption can proceed even if the event date is before `createdOn` or after `expiresOn`.
`targetRuleIds`	Array of Integers	A list of target rule IDs associated with the promotion.
`pageDetails`	Object	Contains pagination information.
• `pageNumber`	Integer	Current page number in the paginated result.
• `pageSize`	Integer	Number of items displayed per page.
• `totalEntries`	Integer	Total number of records available for pagination.
• `pageCount`	Integer	Total number of pages available for the current query and page size.

API specific error codes

Error	Description
8013	Identifier name missing or incorrect.
8015	Identifier value missing or incorrect.
8003	Source is missing or incorrect.
4086	`limit`, `offset`, or `sourceType` is missing
4055	`limit` is greater than 100
4027	`promotionId` or `startRuleIdentifier` doesn't exist
4083	Incorrect event name is passed
4082	`eventName` is null / empty
4084	`sourceType` is empty / null
4085	`sourceType` parameter has an invalid value
4056	All mandatory query parameters are missing
4050	Query parameter is not supported