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
<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
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/469/promotions/57099/get' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic mRmMmQ0NOTMyMWYI=' \
--header 'Cookie: CS=17999bae3c0f41269ea0947f75896090'
Response parameters
Parameter | Type | Description |
---|---|---|
id | Integer | The unique identifier for the promotion. |
name | String | The name of the promotion. |
description | String | A brief description of the promotion. |
promotionStatus | String | The current status of the promotion (e.g., LIVE, PENDING). |
lastUpdateDate | String | The date and time when the promotion was last updated. |
lastUpdatedBy | Integer | The ID of the user who last updated the promotion. |
rulesetInfos | Object | Information about the ruleset associated with the promotion. |
orgName | String | The name of the organization associated with the ruleset. |
contextID | Integer | The ID of the context associated with the ruleset. |
orgID | Integer | The ID of the organization associated with the ruleset. |
contextType | String | The value is Program. |
rules | Array | The rules defined for the promotion. |
id | Integer | The unique identifier for the rule. |
exp | String | The expression defining the rule. |
expJSON | String | The expression in JSON format. |
jsonType | String | The JSON type of the expression. |
isActive | Boolean | Indicates whether the rule is active. |
priority | Integer | The priority of the rule. |
startDate | Integer | The start date of the rule. |
endDate | Integer | The end date of the rule. |
createdOn | Integer | The timestamp when the rule was created. |
caseToActions | Object | The actions to be taken based on the rule. |
ruleScope | String | The scope of the rule (e.g., SERVER, CLIENT). |
createdBy | Integer | The ID of the user who created the rule. |
modifiedBy | Integer | The ID of the user who last modified the rule. |
modifiedOn | Integer | The timestamp when the rule was last modified. |
name | String | The name of the rule. |
description | String | A brief description of the rule. |
expDataType | String | The data type of the expression. |
filterInfo | Object | Information about the filters applied to the rule. |
eventType | String | The type of event associated with the rule. |
cappingInfo | Array | Information about capping associated with the rule. |
updatedViaNewUI | Boolean | Indicates whether the rule was updated via the new UI. |
private | Boolean | Indicates whether the rule is private. |
programName | String | The name of the program associated with the promotion. |
programId | Integer | The ID of the program associated with the promotion. |
startDate | String | The start date of the promotion. |
endDate | String | The end date of the promotion. |
identifier | String | The universally unique identifier for the promotion. |
isActive | Boolean | Indicates whether the promotion is active. |
eventName | String | The name of the event associated with the promotion. |
allocatePointsOn | String | Indicates where the points are allocated. The values is based on the event type. |
limits | Object | Limits and constraints for the promotion. |
pointsPerCustomer | Integer | Maximum points a customer can earn. |
numberOfTimesPerCustomer | Integer | The maximum number of activities per customer that can allocate points. |
totalPointsInPromotion | Integer | The 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 | The type of promotion. 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 |
-- redemptionRestrictions | Object | Contains information on the redemption limits for a promotion. |
--- name | Enum | Type of redemption restriction. Supported values: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.MAX_ALLOWED_TIMES_PER_CUSTOMER : The maximum number of activities (make a transaction, redeem points etc.) a customer can do to earn points.MAX_ALLOWED_POINTS_PER_CUSTOMER :The maximum number of points a customer can earn from a promotion.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.MAX_ALLOWED_POINTS_PER_PROMOTION :The maximum number of points available across all customers in the brand for the promotion.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 the value as -1 for no limit. The maximum limit supported by the system is 100. |
--- type | Enum | Type of period for restriction. Supported values:PERIOD_BASED : Restriction is applied for a defined period of time.NON_PERIOD_BASED : Restriction is applied for the entire duration of the promotion. |
--- periodType | Enum | Type of period for the restriction. Supported value: MOVING_WINDOW . |
--- periodUnit | Enum | Frequency of the period. Supported values: DAILY , WEEKLY , MONTHLY . |
-- issualRestrictions | Object | Contains information on the issual limits for a promotion. |
--- name | Enum | Type of issual restriction. Supported values: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 the value as -1 for no limit. The maximum limit supported by the system is 100. |
-- earnRestrictions | Object | Contains information on the earn limits for a promotion. This is specific for enrol and issue type promotion. |
--- name | Enum | Type of earn restriction. Supported values:MAX_NUMBER_OF_EARNS_PER_CUSTOMER : The maximum number of times a loyalty promotion can be issued to a customer.MAX_NUMBER_OF_EARNS_PER_PROMOTION : The maximum number of times a loyalty promotion can be issued across customers.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 the value as -1 for no limit. The maximum limit supported by the system is 100. |
-- expiryRestrictions\ | Object | Contains information on the expiry for a promotion. This is mandatory for both enrol and issue and direct issue types of promotion. |
--- name\ | Enum | Action that is expiring. Supported values: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.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. Supported values:PROMOTION : The loyalty promotion expires on the date defined in endDate CUSTOM : Define the number of days when the loyalty promotion expires from the date of issual. |
--- value | Integer | Number of days the loyalty promotion expires from the date of issual. |
isAlwaysApply | Boolean | Indicates whether the promotion is always applied. |
isStackable | Boolean | Indicates whether the promotion is stackable. |
isConsideredForRanking | Boolean | Indicates whether the promotion is considered for ranking. |
loyaltyEarningType | String | This parameter is not in use. |
expiryReminder | String | The expiry reminder settings for the promotion. |
isExclusive | Boolean | Indicates 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": [
"loyalty"
]
}
},
{
"id": 126393618,
"orgID": 100458,
"ruleID": -1,
"name": "EventSource",
"className": "com.capillary.shopbook.emf.impl.filter.EventSourceFilterImpl",
"isInclude": true,
"propertyToValues": {
"eventSource": [
"INSTORE"
]
}
}
],
"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 code | Description |
---|---|
4029 | Promotion ID is invalid. |
2010 | Program ID is invalid. |