Lists all promotions.
This API lists and provides details of all the promotions available in the org. This includes the types of promotions, point and redemption restriction details, start and end dates, activation status etc, ranking and stacking information.
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 is enabled for your organisation, then the information regarding the limits and restrictions on issual, earning, or redemption is available in the object promotionRestriction. This information is also replicated in the limits and customerUsage objects.
API endpoint example
'https://eucrm.cc.capillarytech.com/api_gateway/loyalty/v1/programs/promotions/list?limit=5&offset=1
Prerequisites
- Authentication: Basic or OAuth authentication
- Access group resource: Read access to customer group resource
Resource information
URI | /api_gateway/loyalty/v1/programs/promotions/list |
HTTP method | GET |
Pagination supported? | Yes |
Rate limit | NA |
Batch support | No |
Query Parameters
Parameter (Parameters marked with * are mandatory) | Data Type | Description |
---|---|---|
limit* | Integer | Number of entries in a page. |
offset* | Integer | Page number you want to fetch. |
program | Long | Program ID associated with the promotion. |
status | Enum | Status of promotion. Valid values are COMPLETED, LIVE, UPCOMING, INACTIVE. |
activity | Enum | Event name for promotion. Valid values re CustomerRegistration, CustomerUpdate, GenericEvent, NewBill, PointsContributionToGroup, PointsTransfer, ReturnBill,TargetCompleted, TransactionAdd, ALL. |
startDate | String | Start date of the promotion in ISO8601 format. Example: 2024-04-04T00:00Z |
endDate | String | End date of promotion in ISO8601 format. Example: 2024-04-27T23:59:59Z |
promotionName | String | Name of the promotion. In case you want to fetch data of a specific promotion. |
Note: startDate and endDate must appear in pairs.
https://eucrm.cc.capillarytech.com/api_gateway/loyalty/v1/programs/promotions/list?limit=5&offset=1
Response Parameters
Parameter | Data Type | Description |
---|---|---|
status | Object | An object containing the status code and message of the response. |
code | Integer | The status code indicating the result of the request. |
message | String | A message providing additional information about the status. |
validationErrors | Object | An object containing validation errors, if any. |
data | Object | An object containing promotion data retrieved from the request. |
id | Long | The ID of the promotion. |
name | String | The name of the promotion. |
description | String | The description of the promotion. |
promotionStatus | String | The status of the promotion. Values are COMPLETED, LIVE, UPCOMING, or INACTIVE |
lastUpdateDate | String (Date) | The date and time when the promotion was last updated. |
lastUpdatedBy | Integer | The ID of the user who last updated the promotion. |
programName | String | The name of the program associated with the promotion. |
promotionType | String | Identifies where the promotion is applied, if it's customer level promotion or transaction level promotion. |
programId | Long | The ID of the program associated with the promotion. |
startDate | String (Date) | The start date and time of the promotion. |
endDate | String (Date) | The end date and time of the promotion. |
identifier | String | Universally unique identifier of the promotion. |
isActive | Boolean | Indicates if the promotion is currently active. |
eventName | String | The name of the event associated with the promotion. |
pointsOfferType | String | The type of promotion. The types of promotion are GENERIC, LOYALTY, and 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 -1 for no limit (max limit: 100). |
--- type | Enum | Type of period for restriction. Supported values: PERIOD_BASED , NON_PERIOD_BASED . |
--- periodType | Enum | Type of period. 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 -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. 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 -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. 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 , CUSTOM . |
--- 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. |
scope | String | The scope of the promotion. |
cappingStatus | Boolean | Indicates if the loyalty promotion has restrictions on reward currencies. The value will be true or false only if the loyalty promotion has a fixed-window calendar.true : Capping is enabled for the loyalty promotion.false : Capping is disabled for the loyalty promotion.null : Loyalty promotion does not have a fixed-window calendar. |
pageDetails | Object | An object containing details about the pagination of the response. |
pageNumber | Integer | The current page number. |
pageSize | Integer | The number of entries per page. |
totalEntries | Integer | The total number of entries. |
pageCount | Integer | The total number of pages in the response. |
{
"status": {
"code": 200,
"message": "success"
},
"validationErrors": null,
"data": [
{
"id": 56796,
"name": "Happyhour",
"description": "Promotion Description",
"promotionStatus": "INACTIVE",
"lastUpdateDate": "2024-04-16T07:39:05Z",
"lastUpdatedBy": 606249,
"programName": "Default Program",
"promotionType": "BILL",
"programId": 469,
"startDate": "2024-04-04T00:00Z",
"endDate": "2024-04-27T23:59:59Z",
"identifier": "d32dd076-67b2-4b15-b52d-83f9c4785589",
"isActive": false,
"eventName": "TRANSACTIONADD",
"pointsOfferType": "GENERIC",
"promotionRestrictions": {
"restrictions": {
"redemptionRestrictions": [
{
"name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
"value": 100,
"type": "NON_PERIOD_BASED",
"periodType": null,
"periodUnit": null
}
],
"issualRestrictions": [],
"earnRestrictions": [],
"expiryRestrictions": []
},
"scope": null,
"isStackable": false,
"isConsideredForRanking": false,
"loyaltyEarningType": null,
"expiryReminder": null,
"isExclusive": false,
"isAlwaysApply": false,
"cappingStatus": true
}
},
{
"id": 56783,
"name": "Update Profile",
"description": "Promotion Description",
"promotionStatus": "INACTIVE",
"lastUpdateDate": "2024-04-08T07:55:10Z",
"lastUpdatedBy": 606249,
"programName": "Default Program",
"promotionType": "CUSTOMER",
"programId": 469,
"startDate": "2024-04-04T00:00Z",
"endDate": "2024-04-30T23:59:59Z",
"identifier": "c4576641-cce4-475a-aae5-fd2236b2d631",
"isActive": false,
"eventName": "CUSTOMERREGISTRATION",
"pointsOfferType": "GENERIC",
"promotionRestrictions": {
"restrictions": {
"redemptionRestrictions": [
{
"name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
"value": 100,
"type": "NON_PERIOD_BASED",
"periodType": null,
"periodUnit": null
}
],
"issualRestrictions": [],
"earnRestrictions": [],
"expiryRestrictions": []
},
"scope": null,
"isStackable": false,
"isConsideredForRanking": false,
"loyaltyEarningType": null,
"expiryReminder": null,
"isExclusive": false,
"isAlwaysApply": false,
"cappingStatus": true
}
},
{
"id": 56782,
"name": "Specificstores",
"description": "Promotion Description",
"promotionStatus": "INACTIVE",
"lastUpdateDate": "2024-04-08T07:55:32Z",
"lastUpdatedBy": 606249,
"programName": "Default Program",
"promotionType": "BILL",
"programId": 469,
"startDate": "2024-04-04T00:00Z",
"endDate": "2024-04-30T23:59:59Z",
"identifier": "69511a30-b828-485c-9d7a-7a92b4e30bcf",
"isActive": false,
"eventName": "TRANSACTIONADD",
"pointsOfferType": "GENERIC",
"promotionRestrictions": {
"restrictions": {
"redemptionRestrictions": [
{
"name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
"value": 100,
"type": "NON_PERIOD_BASED",
"periodType": null,
"periodUnit": null
}
],
"issualRestrictions": [],
"earnRestrictions": [],
"expiryRestrictions": []
},
"scope": null,
"isStackable": false,
"isConsideredForRanking": false,
"loyaltyEarningType": null,
"expiryReminder": null,
"isExclusive": false,
"isAlwaysApply": false,
"cappingStatus": false
}
},
{
"id": 56747,
"name": "Accumulatepoints",
"description": "Promotion Description",
"promotionStatus": "INACTIVE",
"lastUpdateDate": "2024-04-16T07:39:36Z",
"lastUpdatedBy": 606249,
"programName": "Default Program",
"promotionType": "CUSTOMER",
"programId": 469,
"startDate": "2024-04-03T00:00Z",
"endDate": "2024-04-30T23:59:59Z",
"identifier": "95010c0f-4177-45f4-9888-82d43d42a672",
"isActive": false,
"eventName": "TARGETCOMPLETED",
"pointsOfferType": "GENERIC",
"promotionRestrictions": {
"restrictions": {
"redemptionRestrictions": [
{
"name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
"value": 100,
"type": "NON_PERIOD_BASED",
"periodType": null,
"periodUnit": null
}
],
"issualRestrictions": [],
"earnRestrictions": [],
"expiryRestrictions": []
},
"scope": null,
"isStackable": false,
"isConsideredForRanking": false,
"loyaltyEarningType": null,
"expiryReminder": null,
"isExclusive": false,
"isAlwaysApply": false,
"cappingStatus": false
}
},
{
"id": 56746,
"name": "Trackredeem1",
"description": "Promotion Description",
"promotionStatus": "COMPLETED",
"lastUpdateDate": "2024-04-03T11:22:50Z",
"lastUpdatedBy": 75009908,
"programName": "Default Program",
"promotionType": "CUSTOMER",
"programId": 469,
"startDate": "2024-04-03T00:00Z",
"endDate": "2024-04-10T23:59:59Z",
"identifier": "01a833e1-60e1-45d7-84bc-ba9154d4f86a",
"isActive": true,
"eventName": "TARGETCOMPLETED",
"pointsOfferType": "GENERIC",
"promotionRestrictions": {
"restrictions": {
"redemptionRestrictions": [
{
"name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
"value": 100,
"type": "NON_PERIOD_BASED",
"periodType": null,
"periodUnit": null
}
],
"issualRestrictions": [],
"earnRestrictions": [],
"expiryRestrictions": []
},
"scope": null,
"isStackable": false,
"isConsideredForRanking": false,
"loyaltyEarningType": null,
"expiryReminder": null,
"isExclusive": false,
"isAlwaysApply": false,
"cappingStatus": true
}
}
],
"pageDetails": {
"pageNumber": 1,
"pageSize": 5,
"totalEntries": 88,
"pageCount": 18
}
}
API-specific error codes
Error code | Description |
---|---|
4054 | Offset or limit missing. |
4053 | Start date or end date missing. |
4057 | Start date or end date not in the correct format. |
2010 | Program ID incorrect. |