get https://{host}/v2/customers/lookup/promotionData
Retrieve promotion data of a specific customer.
This API retrieves the promotion data of a specified customer. It provides detailed information on the various promotions the customer is associated with within a loyalty program. This includes the types of promotions, point and redemption restriction details, start and end dates, and activation status.
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.
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 object promotionRestriction. This information is also replicated in the limits and customerUsage objects.
If your organisation does not have the Types of promotions enabled, the details on the limits and restrictions are available only in the limits and customerUsage objects.
API endpoint example
(https://eucrm.cc.capillarytech.com/v2/customers/lookup/promotionData?identifierName=externalId&identifierValue=000003873354&source=INSTORE&limit=10&offset=0)
Prerequisites
- Authentication: Basic or OAuth credentials
- Access group resource: Read access to customer group resource
Resource information
| URI | /v2/customers/lookup/promotionData |
| HTTP Method | GET |
| Pagination | Yes |
| Batch support | No |
| Rate limit information | NA |
Query parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| identifierName* | String | Identifier type to identify the customer. |
| identifierValue* | String | Value for the identifier. |
| source* | String | Source from which you want to fetch the customer details. |
| limit | String | Number of results that need to be displayed. The values from zero to a maximum of 100 are supported. |
| offset | String | Start index for data retrieval. This value should not be negative. |
https://eucrm.cc.capillarytech.com/v2/customers/lookup/promotionData?identifierName=externalId&identifierValue=000003873354&source=INSTORE&limit=10&offset=0
Response parameters
| Parameter | Data Type | Description |
|---|---|---|
| pageDetails | Object | Object containing pagination details. |
| - pageNumber | Integer | Page number of the current result set. |
| - pageSize | Integer | Number of entries per page. |
| - totalEntries | Integer | Total number of entries in the result set. |
| - pageCount | Integer | Total number of pages in the result set. |
| customerId | Integer | Identifier of the customer. |
| promotions | Object | An object containing details of promotions. |
| - promotionId | Integer | Unique identifier for the promotion issued to the customer. |
| - promotionName | String | Name of the promotion. |
| - programId | Integer | Identifier of the loyalty program associated with the promotion. |
| - startDate | String | Start date of the promotion. |
| - endDate | String | End date of the promotion. |
| - identifier | String | Universally Unique Identifier for the promotion. |
| - description | String | Description of the promotion. |
| - active | Boolean | Indicates if the promotion is active. |
| - eventName | String | Event triggering the promotion. |
| - promotionMetadata | Object | Array containing metadata for the promotion. |
| - - key | String | Key of the metadata. |
| - - value | String | Value of the metadata. |
| - - brandDefined | Boolean | Indicates if the metadata is brand-defined. |
| - limits | Object | Object containing limits set for the promotion. |
| - - maxPointsPerEvent | Integer | Maximum number of points offered per event. |
| - - 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. |
| - customerUsage | Object | Object containing customer usage details. |
| - - currentPointsPerCustomer | String | The current points accrued by the customer. |
| - - currentNumberOfTimesPerCustomer | Integer | The number of activities through which the customer has received the points. |
| - - currentTotalPointsInPromotion | String | The points received by all customers within the promotion duration. |
| - pointsOfferType | String | Type of promotion. The types of promotion are GENERIC, LOYALTY, and LOYALTY_EARNING. |
| - promotionRestriction | Object | Object containing promotion restriction details. Information in this field is replicated if Advanced loyalty Promotion is available in your org. |
| - - issualRestrictions | Object | Array containing issual restriction details. |
| - - - kpi | String | Key performance indicator for the restriction. The KPI values are NUMBER_OF_EARNS, NUMBER_OF_ISSUALS, NUMBER_OF_TIMES, and NUMBER_OF_POINTS. |
| - - - maxLimit | String | Maximum times a customer can be enrolled in a promotion. |
| - - - currentCustomerUsage | String | The present count of a customer's enrolment in a promotion. |
| - - - limitOn | String | Specifies what the limit applies to. The values are EVENT, CUSTOMER, or PROMOTION. |
| - - earnRestrictions | Object | Array containing earn restriction details. |
| - - - kpi | String | Key performance indicator for the restriction. The KPI values are NUMBER_OF_EARNS, NUMBER_OF_ISSUALS, NUMBER_OF_TIMES, and NUMBER_OF_POINTS. |
| - - - maxLimit | String | Maximum times a promotion can be issued to a customer. |
| - - - currentCustomerUsage | String | The present number of instances a promotion is issued to the customer. |
| - - - limitOn | String | Specifies what the limit applies to. The values are EVENT, CUSTOMER, or PROMOTION. |
| - - redemptionRestrictions | Object | Array containing redemption restriction details. |
| - - - kpi | String | Key performance indicator for the restriction. The KPI values are NUMBER_OF_EARNS, NUMBER_OF_ISSUALS, NUMBER_OF_TIMES, and NUMBER_OF_POINTS. |
| - - - maxLimit | String | Maximum number of times the points can be availed. |
| - - - currentCustomerUsage | String | The present number of points availed by the customer. |
| - - - limitOn | String | Specifies what the limit applies to. The values are EVENT, CUSTOMER, or PROMOTION. |
| - - - type | String | Type of restrictions. The values are NON_PERIOD_BASED or PERIOD_BASED. |
| warnings | Object | An array containing any warnings. |
{
"pageDetails": {
"pageNumber": 0,
"pageSize": 10,
"totalEntries": 8,
"pageCount": 1
},
"customerId": 555380204,
"promotions": [
{
"promotionId": 56800,
"promotionName": "issue promotion 1",
"programId": 469,
"startDate": "2024-04-04T00:00:00.000Z",
"endDate": "2024-05-31T23:59:59.000Z",
"identifier": "f2604502-3356-4994-a9d0-2608cb86702e",
"description": "Promotion Description",
"active": true,
"eventName": "TransactionAdd",
"promotionMetadata": [
{
"key": "No. of steps",
"value": "500",
"brandDefined": true
},
{
"key": "preferred language",
"value": "english",
"brandDefined": true
}
],
"limits": {
"maxPointsPerEvent": "10",
"pointsPerCustomer": "1000",
"numberOFTimesPerCustomer": 10,
"totalPointsInPromotion": "1000"
},
"customerUsage": {
"currentPointsPerCustomer": "0",
"currentNumberOfTimesPerCustomer": 0,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "GENERIC",
"promotionRestriction": {
"issualRestrictions": [],
"earnRestrictions": [],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "10",
"limitOn": "EVENT",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_TIMES",
"maxLimit": "10",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "1000",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_TIMES",
"maxLimit": "100",
"currentCustomerUsage": "0",
"limitOn": "PROMOTION",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "1000",
"currentCustomerUsage": "0",
"limitOn": "PROMOTION",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "100",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
}
},
{
"promotionId": 56746,
"promotionName": "Trackredeem1",
"programId": 469,
"startDate": "2024-04-03T00:00:00.000Z",
"endDate": "2024-04-10T23:59:59.000Z",
"identifier": "01a833e1-60e1-45d7-84bc-ba9154d4f86a",
"description": "Promotion Description",
"active": true,
"eventName": "TargetCompleted",
"limits": {
"maxPointsPerEvent": "0",
"pointsPerCustomer": "0",
"numberOFTimesPerCustomer": 0,
"totalPointsInPromotion": "0"
},
"customerUsage": {
"currentPointsPerCustomer": "0",
"currentNumberOfTimesPerCustomer": 0,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "GENERIC",
"promotionRestriction": {
"issualRestrictions": [],
"earnRestrictions": [],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "100",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
}
},
{
"promotionId": 56695,
"promotionName": "Spend100NFR",
"programId": 469,
"startDate": "2024-04-02T00:00:00.000Z",
"endDate": "2024-04-10T23:59:59.000Z",
"identifier": "32e6c3b9-8f27-4f37-884e-b139a3e77dbd",
"description": "Spend100NFR",
"active": true,
"eventName": "TransactionAdd",
"limits": {
"maxPointsPerEvent": "0",
"pointsPerCustomer": "0",
"numberOFTimesPerCustomer": 0,
"totalPointsInPromotion": "0"
},
"customerUsage": {
"currentPointsPerCustomer": "0",
"currentNumberOfTimesPerCustomer": 0,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "GENERIC",
"promotionRestriction": {
"issualRestrictions": [],
"earnRestrictions": [],
"redemptionRestrictions": []
}
},
{
"promotionId": 56690,
"promotionName": "Metro - 50% Bonus Points ",
"programId": 469,
"startDate": "2024-04-02T00:00:00.000Z",
"endDate": "2024-05-22T23:59:59.000Z",
"identifier": "5beea349-919b-4a9e-944b-5892b2ed9fe2",
"description": "Metro - 50% Bonus Points ",
"active": true,
"eventName": "TargetCompleted",
"limits": {
"maxPointsPerEvent": "0",
"pointsPerCustomer": "0",
"numberOFTimesPerCustomer": 0,
"totalPointsInPromotion": "0"
},
"customerUsage": {
"currentPointsPerCustomer": "0",
"currentNumberOfTimesPerCustomer": 0,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "GENERIC",
"promotionRestriction": {
"issualRestrictions": [],
"earnRestrictions": [],
"redemptionRestrictions": []
}
},
{
"promotionId": 56452,
"promotionName": "Loyalty_Badges2",
"programId": 469,
"startDate": "2024-03-28T00:00:00.000Z",
"endDate": "2024-06-30T23:59:59.000Z",
"identifier": "6f50e886-27c5-4c37-9b81-97f51ab05cff",
"description": "Loyalty_Badges2",
"active": true,
"eventName": "TargetCompleted",
"limits": {
"maxPointsPerEvent": "0",
"pointsPerCustomer": "0",
"numberOFTimesPerCustomer": 0,
"totalPointsInPromotion": "0"
},
"customerUsage": {
"currentPointsPerCustomer": "0",
"currentNumberOfTimesPerCustomer": 0,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "GENERIC",
"promotionRestriction": {
"issualRestrictions": [],
"earnRestrictions": [],
"redemptionRestrictions": []
}
},
{
"promotionId": 56799,
"promotionName": "test direct issue1",
"programId": 469,
"startDate": "2024-04-04T00:00:00.000Z",
"endDate": "2024-05-31T23:59:59.000Z",
"identifier": "33f9564c-4b91-4beb-b21b-7c9463d8c29d",
"description": "Promotion Description",
"active": true,
"eventName": "TransactionAdd",
"limits": {
"maxPointsPerEvent": "10",
"pointsPerCustomer": "100",
"numberOFTimesPerCustomer": 100,
"totalPointsInPromotion": "1000"
},
"customerUsage": {
"currentPointsPerCustomer": "10.000",
"currentNumberOfTimesPerCustomer": 1,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "LOYALTY",
"promotionRestriction": {
"issualRestrictions": [
{
"kpi": "NUMBER_OF_ISSUALS",
"maxLimit": "100",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER"
}
],
"earnRestrictions": [],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "10",
"limitOn": "EVENT",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_TIMES",
"maxLimit": "100",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "100",
"currentCustomerUsage": "10.000",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_TIMES",
"maxLimit": "1000",
"currentCustomerUsage": "0",
"limitOn": "PROMOTION",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "1000",
"currentCustomerUsage": "0",
"limitOn": "PROMOTION",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "100",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
}
},
{
"promotionId": 57092,
"promotionName": "Divya_Test_Promotion",
"programId": 469,
"startDate": "2024-04-10T00:00:00.000Z",
"endDate": "2024-05-31T23:59:59.000Z",
"identifier": "1858e8b2-8c76-4166-8ced-ec50a9846f66",
"description": "Divya_Test_Promotion",
"active": true,
"eventName": "TransactionAdd",
"limits": {
"maxPointsPerEvent": "0",
"pointsPerCustomer": "0",
"numberOFTimesPerCustomer": 0,
"totalPointsInPromotion": "0"
},
"customerUsage": {
"currentPointsPerCustomer": "100.000",
"currentNumberOfTimesPerCustomer": 1,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "LOYALTY",
"promotionRestriction": {
"issualRestrictions": [
{
"kpi": "NUMBER_OF_ISSUALS",
"maxLimit": "1",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER"
}
],
"earnRestrictions": [],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "1",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
}
},
{
"promotionId": 57099,
"promotionName": "test enroll and issue",
"programId": 469,
"startDate": "2024-04-10T00:00:00.000Z",
"endDate": "2024-05-31T23:59:59.000Z",
"identifier": "10c2fc95-acd4-476b-9784-9ccb7a410874",
"description": "Promotion Description",
"active": true,
"eventName": "TransactionAdd",
"limits": {
"maxPointsPerEvent": "0",
"pointsPerCustomer": "0",
"numberOFTimesPerCustomer": 0,
"totalPointsInPromotion": "0"
},
"customerUsage": {
"currentPointsPerCustomer": "0",
"currentNumberOfTimesPerCustomer": 0,
"currentTotalPointsInPromotion": "0"
},
"pointsOfferType": "LOYALTY_EARNING",
"promotionRestriction": {
"issualRestrictions": [
{
"kpi": "NUMBER_OF_ISSUALS",
"maxLimit": "10",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER"
}
],
"earnRestrictions": [
{
"kpi": "NUMBER_OF_EARNS",
"maxLimit": "10",
"currentCustomerUsage": "2",
"limitOn": "CUSTOMER"
}
],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "10",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
}
}
],
"warnings": []
}
"pointsOfferType": "GENERIC",
"promotionRestriction": {
"issualRestrictions": [],
"earnRestrictions": [],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "100",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
"pointsOfferType": "LOYALTY",
"promotionRestriction": {
"issualRestrictions": [
{
"kpi": "NUMBER_OF_ISSUALS",
"maxLimit": "100",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER"
}
],
"earnRestrictions": [],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "10",
"limitOn": "EVENT",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_TIMES",
"maxLimit": "100",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "100",
"currentCustomerUsage": "10.000",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_TIMES",
"maxLimit": "1000",
"currentCustomerUsage": "0",
"limitOn": "PROMOTION",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_POINTS",
"maxLimit": "1000",
"currentCustomerUsage": "0",
"limitOn": "PROMOTION",
"type": "NON_PERIOD_BASED"
},
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "100",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
"pointsOfferType": "LOYALTY_EARNING",
"promotionRestriction": {
"issualRestrictions": [
{
"kpi": "NUMBER_OF_ISSUALS",
"maxLimit": "10",
"currentCustomerUsage": "1",
"limitOn": "CUSTOMER"
}
],
"earnRestrictions": [
{
"kpi": "NUMBER_OF_EARNS",
"maxLimit": "10",
"currentCustomerUsage": "2",
"limitOn": "CUSTOMER"
}
],
"redemptionRestrictions": [
{
"kpi": "NUMBER_OF_REDEMPTIONS_PER_EARN",
"maxLimit": "10",
"currentCustomerUsage": "0",
"limitOn": "CUSTOMER",
"type": "NON_PERIOD_BASED"
}
]
API specific error codes
| Error | Description |
|---|---|
| 8013 | Identifier name missing or incorrect. |
| 8015 | Identifier value missing or incorrect. |
| 8003 | Source is missing or incorrect. |