Get promotion by ID

Get details of the promotion using promotion ID.

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



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

Resource information

HTTP methodGET
Pagination supported?No
Rate limitNA
Batch supportNA

Path parameters

programs*LongUnique program ID.
promotions*LongUnique promotion ID.
curl --location '' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic mRmMmQ0NOTMyMWYI=' \
--header 'Cookie: CS=17999bae3c0f41269ea0947f75896090'

Response parameters

idIntegerThe unique identifier for the promotion.
nameStringThe name of the promotion.
descriptionStringA brief description of the promotion.
promotionStatusStringThe current status of the promotion (e.g., LIVE, PENDING).
lastUpdateDateStringThe date and time when the promotion was last updated.
lastUpdatedByIntegerThe ID of the user who last updated the promotion.
rulesetInfosObjectInformation about the ruleset associated with the promotion.
orgNameStringThe name of the organization associated with the ruleset.
contextIDIntegerThe ID of the context associated with the ruleset.
orgIDIntegerThe ID of the organization associated with the ruleset.
contextTypeStringThe value is Program.
rulesArrayThe rules defined for the promotion.
idIntegerThe unique identifier for the rule.
expStringThe expression defining the rule.
expJSONStringThe expression in JSON format.
jsonTypeStringThe JSON type of the expression.
isActiveBooleanIndicates whether the rule is active.
priorityIntegerThe priority of the rule.
startDateIntegerThe start date of the rule.
endDateIntegerThe end date of the rule.
createdOnIntegerThe timestamp when the rule was created.
caseToActionsObjectThe actions to be taken based on the rule.
ruleScopeStringThe scope of the rule (e.g., SERVER, CLIENT).
createdByIntegerThe ID of the user who created the rule.
modifiedByIntegerThe ID of the user who last modified the rule.
modifiedOnIntegerThe timestamp when the rule was last modified.
nameStringThe name of the rule.
descriptionStringA brief description of the rule.
expDataTypeStringThe data type of the expression.
filterInfoObjectInformation about the filters applied to the rule.
eventTypeStringThe type of event associated with the rule.
cappingInfoArrayInformation about capping associated with the rule.
updatedViaNewUIBooleanIndicates whether the rule was updated via the new UI.
privateBooleanIndicates whether the rule is private.
programNameStringThe name of the program associated with the promotion.
programIdIntegerThe ID of the program associated with the promotion.
startDateStringThe start date of the promotion.
endDateStringThe end date of the promotion.
identifierStringThe universally unique identifier for the promotion.
isActiveBooleanIndicates whether the promotion is active.
eventNameStringThe name of the event associated with the promotion.
allocatePointsOnStringIndicates where the points are allocated. The values is based on the event type.
limitsObjectLimits and constraints for the promotion.
pointsPerCustomerIntegerMaximum points a customer can earn.
numberOfTimesPerCustomerIntegerThe maximum number of activities per customer that can allocate points.
totalPointsInPromotionIntegerThe maximum points permitted across customers within the promotion duration.
totalPointsPerEventLimitIntegerLimit on the total points that can be earned per event within the promotion.
useProportionsBooleanIndicates whether proportions are used for the promotion.
pointsOfferTypeStringThe type of promotion. GENERIC/LOYALTY/LOYALTY_EARNING
promotionRestrictionsObjectRestrictions 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
isAlwaysApplyBooleanIndicates whether the promotion is always applied.
isStackableBooleanIndicates whether the promotion is stackable.
isConsideredForRankingBooleanIndicates whether the promotion is considered for ranking.
loyaltyEarningTypeStringThis parameter is not in use.
expiryReminderStringThe expiry reminder settings for the promotion.
isExclusiveBooleanIndicates whether the promotion is exclusive.
    "status": {
        "code": 200,
        "message": "success"
    "validationErrors": null,
    "data": [
            "id": 57099,
            "name": "test enroll and issue",
            "description": "Promotion Description",
            "promotionStatus": "LIVE",
            "lastUpdateDate": "2024-04-10T12:59:11Z",
            "lastUpdatedBy": 75069206,
            "rulesetInfos": [
                    "id": 126289300,
                    "orgName": "Bukl Enterprises",
                    "contextID": 469,
                    "orgID": 100458,
                    "contextType": "program",
                    "rules": [
                            "id": 126450375,
                            "exp": "true",
                            "expJSON": "{ \"arity\": \"literal\", \"value\": \"true\", \"type\": \"boolean:primitive\" }",
                            "jsonType": "JNODE",
                            "isActive": true,
                            "priority": -1,
                            "startDate": 1081601860018,
                            "endDate": 33585195460018,
                            "createdOn": 1712753899436,
                            "caseToActions": {
                                "true": [
                                        "id": 126590124,
                                        "actionName": "PE_ISSUE_VOUCHER_ACTION",
                                        "actionClass": "com.capillary.shopbook.pointsengine.endpoint.impl.action.PointsEngineIssueVoucherActionImpl",
                                        "mandatoryPropertiesValues": {
                                            "VoucherSeriesId": "349357"
                                        "mandatoryComplexPropertiesValues": {},
                                        "description": "17% off on all products"
                            "ruleScope": "SERVER",
                            "createdBy": 5036393,
                            "modifiedBy": 5036393,
                            "modifiedOn": 1712753950845,
                            "name": "Rule 1",
                            "description": "",
                            "expDataType": null,
                            "filterInfo": [],
                            "ruleSetId": 126289300,
                            "updatedViaNewUI": false
                    "ruleScope": "SERVER",
                    "startDate": 1712707200000,
                    "endDate": 1717199999000,
                    "createdOn": 1712753899436,
                    "createdBy": 5036393,
                    "modifiedBy": 5036393,
                    "modifiedOn": 1712753950845,
                    "name": "ruleset_20240410125740",
                    "packageName": "",
                    "description": "",
                    "filterInfo": [
                            "id": 126393617,
                            "orgID": 100458,
                            "ruleID": -1,
                            "name": "LoyaltyType",
                            "className": "com.capillary.shopbook.emf.impl.filter.LoyaltyTypeFilterImpl",
                            "isInclude": true,
                            "propertyToValues": {
                                "loyaltyType": [
                            "id": 126393618,
                            "orgID": 100458,
                            "ruleID": -1,
                            "name": "EventSource",
                            "className": "com.capillary.shopbook.emf.impl.filter.EventSourceFilterImpl",
                            "isInclude": true,
                            "propertyToValues": {
                                "eventSource": [
                    "eventType": null,
                    "cappingInfo": [],
                    "updatedViaNewUI": false,
                    "private": false
            "programName": "Default Program",
            "programId": 469,
            "startDate": "2024-04-10T00:00Z",
            "endDate": "2024-05-31T23:59:59Z",
            "identifier": "10c2fc95-acd4-476b-9784-9ccb7a410874",
            "isActive": true,
            "eventName": "TRANSACTIONADD",
            "allocatePointsOn": "BILL",
            "limits": {
                "pointsPerCustomer": 0,
                "numberOfTimesPerCustomer": 0,
                "totalPointsInPromotion": 0,
                "totalPointsPerEventLimit": 0
            "useProportions": false,
            "pointsOfferType": "LOYALTY_EARNING",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 10,
                            "type": "NON_PERIOD_BASED",
                            "periodType": "MOVING_WINDOW",
                            "periodUnit": "DAILY"
                    "issualRestrictions": [
                            "name": "MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER",
                            "value": 10
                    "earnRestrictions": [
                            "name": "MAX_NUMBER_OF_EARNS_PER_CUSTOMER",
                            "value": 10
                            "name": "MAX_POINTS_PER_EARN_PER_CUSTOMER",
                            "value": -1
                    "expiryRestrictions": [
                            "name": "EARN_PROMOTION_EXPIRY_BASED_ON",
                            "value": 0,
                            "type": "PROMOTION"
                            "name": "ISSUAL_PROMOTION_EXPIRY_BASED_ON",
                            "value": 0,
                            "type": "PROMOTION"
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": false,
                "loyaltyEarningType": "ISSUE_AND_EARN",
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false

API-specific error codes

Error codeDescription
4029Promotion ID is invalid.
2010Program ID is invalid.

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