post https://{host}/v2/promotion/bulk/enrolAndEarn
Enrol & issue promotions, also referred to as LOYALTY_EARNING in the backend, require customers to opt-in or be enrolled before receiving the promotion for a specific activity. Upon meeting the requirements outlined in the issued promotion, customers earn the associated benefits. This API is used to enrol or issue a promotion (associated with the Enrol&Issue promotion type) in bulk to customers. You can also use this API to issue a single promotion.
Note
This API is used to enrol/issue a single promotion to multiple customers. You cannot use this API to enrol/issue multiple promotions to single or multiple customers.
Terminologies
The table below highlights backend terminologies and their corresponding terms used in the UI/frontend:
| UI/Frontend terminology | Backend terminology | Description |
|---|---|---|
| Enrol | Issue | The customer is enrolled into a promotion. |
| Issue | Earn | The customer completes the required activity to earn the promotion. Once the promotion is earned, the customer can fulfil the criteria to receive the associated benefits. |
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
Resource information
| URI | promotion/bulk/enrolAndEarn |
| HTTP method | POST |
| Pagination supported? | NA |
| Rate limit | NA |
| Batch support | NA |
Body parameters
| Parameter | Data Type | Description |
|---|---|---|
| type | Enum | Indicates the entity type. Only the "CUSTOMER" entity is supported (Case sensitive). |
| bulkAction | Enum | The bulk action to be performed. Supported values: "EARN" to issue promotion to the customers and "ENROL" to enrol customers in a promotion. |
| promotionDetails | Object | Details of the promotion to enrol the customer in. |
| programId | Integer | The ID of the loyalty program. |
| promotionId | Integer | The ID of the specific promotion. |
| identifierName | Enum | The identifier type for the customer. Supported identifiers: "id" (customer ID), "mobile", and "email". |
| customers | Array | List of customers on whom the action will be performed. |
| identifierValue | String | The specific identifier value for the identifier type defined in the identifierName. |
| source | Enum | The source of the customer's registration, e.g., "INSTORE". |
{
"type" : "CUSTOMER",
"bulkAction" : "EARN",
"promotionDetails" : {
"programId": 469,
"promotionId":57099
},
"identifierName":"id",
"customers":
[
{
"identifierValue":"554537019",
"source":"INSTORE"
},
{
"identifierValue":"555567088",
"source":"INSTORE"
}
]
}
Response parameters
| Parameter | Data Type | Description |
|---|---|---|
| response | Array | List of response objects. |
| result | Object | Contains the result details for each entity. |
| entityType | String | The type of the entity. |
| entityId | Integer | The unique identifier of the entity. |
| promoIdentifier | String | The identifier for the promotion. |
| programId | Integer | The ID of the program associated with the promotion. |
| issualId | String | The ID of the program generated when promotion is issued. |
| earnedId | String | The ID of the program generated when promotion is earned. |
| errors | Array | List of errors encountered. |
| warnings | Array | List of warnings encountered. |
| totalCount | Integer | The total count of successful responses. |
| failureCount | Integer | The count of failed responses. |
{
"response": [
{
"result": {
"entityType": "CUSTOMER",
"entityId": 554537019,
"promotionId": 57099,
"programId": 469,
"issualId": "39",
"earnedId": "69"
},
"errors": [],
"warnings": []
},
{
"result": {
"entityType": "CUSTOMER",
"entityId": 555567088,
"promotionId": 57099,
"programId": 469,
"issualId": "37",
"earnedId": "70"
},
"errors": [],
"warnings": []
}
],
"totalCount": 2,
"failureCount": 0
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8892,
"message": "promotion is inactive"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8015,
"message": "Customer not found for the given identifiers"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 1101,
"message": "invalid programId passed"
}
],
"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,
"code": 8899,
"message": "Cannot enrol/issue to the user group"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8881,
"message": "insufficient parameters passed, program id and one of promotion id/identifier are required"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8881,
"message": "insufficient parameters passed, program id and one of promotion id/identifier are required"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
API-specific error codes
| Error Code | Description |
|---|---|
| 8892 | Promotion is inactive |
| 8015 | Customer not found for the given identifiers |
| 1101 | Invalid programId passed |
| 8874 | Promotion ID passed is invalid |
| 8899 | Cannot enrol/issue to the user group. This happens when you define USERGROUP2 as the entity. |
| 8881 | Insufficient parameters passed; program ID and one of the promotion ID/identifiers are required |