Enrol a customer or issue a promotion to a customer
This API is used to:
- Enrol in promotion of type enrol & issue (single/bulk)
- Issue promotion of type enrol & issue (single/bulk)
- Issue promotion of type Direct Issue (single/bulk)
Refer to the documentation on loyalty promotions for more information on the types of loyalty promotions.
Terminologies
The table below highlights the UI/frontend terminologies and their corresponding backend terms for enrolling and issuing promotions to a customer.
UI/Frontend terminology | Backend terminology | Description |
---|---|---|
Enrol | Issue | Enrol a customer into a promotion. After enrolment, a promotion must be issued making the customer eligible to earn benefits upon meeting the defined criteria. A customer must be enrolled to the promotion and then issued the promotion in an Enrol and Issue type promotion. |
Issue | Earn | Issue a promotion to a customer. Once issued, the customer is eligible to earn benefits upon meeting the defined criteria. A customer can be directly issued a promotion in a Direct Issue type promotion. |
Enrol and Issue | LOYALTY_EARNING or ISSUE_AND_EARN | Customers must first opt-in or enrol, then achieve the criteria to earn a promotion. |
Direct Issue | LOYALTY or DIRECT | Customers directly earn a promotion once they achieve the criteria |
API endpoint example
https://eucrm.cc.capillarytech.com/v2/promotion/bulk/enrolAndEarn
Prerequisites
- Authentication - Basic or OAuth authentication
- Access group resource - Write access to customer group resource
- Loyalty programId and promotionId
Resource information
URI | promotion/bulk/enrolAndEarn |
HTTP method | POST |
Pagination supported? | NA |
Rate limit | NA |
Batch support | Yes |
Body parameters
Parameter (Parameters marked as * are required) | Data Type | Description |
---|---|---|
type* |
Enum |
Type of entity. Supported entity |
bulkAction |
Enum |
Action to be performed. Refer to the Supported Actions section for the bulk actions available for each type of promotion. |
promotionDetails |
Object |
Details of the promotion where the action is performed. |
|
Integer |
Unique ID of the loyalty program. |
|
Integer |
Unique ID of the loyalty promotion. Either |
|
String |
Unique external identifier of the promotion that is configured. Either |
identifierName* |
Enum |
The identifier type for the customer. Supported identifiers: |
customers |
Object |
List of customers on whom the action will be performed. |
|
String |
Identifier value for the identifier type defined in |
|
Enum |
The source of the customer's registration. |
{
"type" : "CUSTOMER",
"bulkAction" : "ENROL",
"promotionDetails" : {
"programId": 469,
"promotionId":57099
},
"identifierName":"id",
"customers":
[
{
"identifierValue":"555567088",
"source":"INSTORE"
}
]
}
{
"type" : "CUSTOMER",
"bulkAction" : "ENROL",
"promotionDetails" : {
"programId": 469,
"promotionId":69218
},
"identifierName":"mobile",
"customers":
[
{
"identifierValue":"11223569865",
"source":"INSTORE"
},
{
"identifierValue":"919986000586",
"source":"INSTORE"
}
]
}
{
"type" : "CUSTOMER",
"bulkAction" : "EARN",
"promotionDetails" : {
"programId": 469,
"promotionId":57099
},
"identifierName":"id",
"customers":
[
{
"identifierValue":"555567088",
"source":"INSTORE"
}
]
}
{
"type" : "CUSTOMER",
"bulkAction" : "EARN",
"promotionDetails" : {
"programId": 469,
"promotionId":69218
},
"identifierName":"mobile",
"customers":
[
{
"identifierValue":"11223569865",
"source":"INSTORE"
},
{
"identifierValue":"919986000586",
"source":"INSTORE"
}
]
}
Supported Action for the Promotion Type
The table below highlights the supported bulkAction
for each type of promotion.
Promotion Type | Supported Bulk Action | Example |
---|---|---|
Enrol and Issue | ENROL |
A customer is enrolled in a promotion for making a purchase worth ₹5000. If they review the product, they can earn a discount voucher for their next purchase. |
EARN |
If the customer completes the review, they earn the discount coupon. | |
Direct Issue | EARN |
A customer is issued a promotion for making five purchases and earns a free item for completing the task. |
Response parameters
Parameter | Data Type | Description |
---|---|---|
response |
Array |
List of response objects. |
result |
Object |
Contains the details for a customer. |
entityType |
String |
Type of entity. Supported entity |
entityId |
Integer |
Unique identifier of the entity. |
promotionId |
Integer |
Unique ID of the loyalty promotion . |
promoIdentifier* |
String |
Unique external identifier of the loyalty promotion that is configured. |
programId |
Integer |
ID of the loyalty program associated with the promotion. |
issualId |
String |
Unique ID generated when the customer is enrolled to a promotion. **Note: ** If the |
earnedId |
String |
Unique ID generated when the customer is issued a loyalty promotion. |
errors |
Array |
List of errors encountered. |
warnings |
Array |
List of warnings encountered. |
totalCount |
Integer |
Total count of successful responses. |
failureCount |
Integer |
Count of failed responses. |
{
"response": [
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926199,
"promotionId": 202188,
"programId": 2714,
"issualId": "847"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926198,
"promotionId": 202188,
"programId": 2714,
"issualId": "848"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926200,
"promotionId": 202188,
"programId": 2714,
"issualId": "849"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926201,
"promotionId": 202188,
"programId": 2714,
"issualId": "850"
},
"errors": [],
"warnings": []
}
],
"totalCount": 4,
"failureCount": 0
}
{
"response": [
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926199,
"promotionId": 202188,
"programId": 2714,
"issualId": "847",
"earnedId": "840"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926198,
"promotionId": 202188,
"programId": 2714,
"issualId": "848",
"earnedId": "841"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926200,
"promotionId": 202188,
"programId": 2714,
"issualId": "849",
"earnedId": "842"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926201,
"promotionId": 202188,
"programId": 2714,
"issualId": "850",
"earnedId": "843"
},
"errors": [],
"warnings": []
}
],
"totalCount": 4,
"failureCount": 0
}
{
"response": [
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926199,
"promotionId": 202090,
"programId": 2714,
"issualId": "837", //this is a dummy Id
"earnedId": "794"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926198,
"promotionId": 202090,
"programId": 2714,
"issualId": "838", //this is a dummy Id
"earnedId": "795"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926200,
"promotionId": 202090,
"programId": 2714,
"issualId": "839",
"earnedId": "796"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 423926201,
"promotionId": 202090,
"programId": 2714,
"issualId": "840", //this is a dummy Id
"earnedId": "797"
},
"errors": [],
"warnings": []
}
],
"totalCount": 4,
"failureCount": 0
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "bulk action passed not supported for loyalty/generic promotion type",
"code": 8902
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"result": {
"entityType": "CUSTOMER",
"entityId": 170940055,
"promotionId": 74116,
"programId": 699,
"issualId": "72",
"earnedId": "102"
},
"errors": [],
"warnings": []
},
{
"errors": [
{
"status": false,
"code": 8015,
"message": "Customer not found for the given identifiers"
}
],
"warnings": []
},
{
"errors": [
{
"status": false,
"code": 8015,
"message": "Customer not found for the given identifiers"
}
],
"warnings": []
},
{
"errors": [
{
"status": false,
"code": 8015,
"message": "Customer not found for the given identifiers"
}
],
"warnings": []
}
],
"totalCount": 4,
"failureCount": 3
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "invalid programId passed",
"code": 1101
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "promotion is inactive",
"code": 8892
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8874,
"message": "promotion id passed is invalid"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "Error occurred while issuing promotion to the customer",
"code": 8896
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "invalid entity type passed",
"code": 8901
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
API-specific error codes
Error Code | Description | Reason |
---|---|---|
8892 | Promotion is inactive | Promotion is currently inactive. |
8015 | Customer not found for the given identifiers | Customer is not part of the loyalty program or the customer ID is invalid. |
1101 | Invalid programId passed | Program ID is invalid. |
8874 | Promotion ID passed is invalid | Promotion ID is invalid. |
8899 | Cannot enrol/issue to the user group. | A user group cannot be enrolled to a promotion. |
8881 | Insufficient parameters passed; program ID and one of the promotion ID/identifiers are required | Required parameters are not passed. |
8901 | invalid entity type passed | The entity type is invalid or unsupported. |
11013 | identifierName, identifierValue, source can not be empty | The fields mentioned are invalid or empty. |