post https://{host}/v2/promotion/bulk/revokeDirectEarn
This API is used to revoke issued promotions (defined as ENROL in the backend) for customers in bulk. You can also use this API to revoke the promotion issued to a single customer.
Note
This API applies only to the
LOYALTYpromotion type.
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://eu.api.capillarytech.com/v2/promotion/bulk/revokeDirectEarn
Prerequisites
- Authentication - Basic or OAuth authentication
- Access group resource - Write access to customer group resource
Resource information
| URI | v2/promotion/bulk/revokeDirectEarn |
| HTTP method | POST |
| Pagination supported? | NA |
| Rate limit | NA |
| Batch support | NA |
Body parameters
| Parameter | Data Type | Description |
|---|---|---|
type* | String | Indicates the entity type. Only the "CUSTOMER" entity is supported (Case sensitive). |
promotionDetails* | Object | Contains details about the promotion and program. |
programId* | Integer | The ID of the loyalty program. |
promotionId* | Integer | The ID of the specific promotion. |
identifierName* | String | 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. |
| earnIDs | Array | List of IDs of the earned promotions that need to be revoked. If this parameter is not defined, all earned promotions for the respective customers will be revoked. |
identifierValue* | String | The specific identifier value for the identifier type defined in the identifierName. |
source* | String | The source of the customer registration, e.g., "INSTORE". |
{
"type":"CUSTOMER",
"bulkAction":"REVOKE_EARN",
"promotionDetails" : {
"programId": 469,
"promotionId":5709
},
"identifierName":"id",
"customers":
[ {
"identifierValue":"98662653",
"source":"INSTORE"
},
{
"identifierValue":"98662953",
"source":"INSTORE"
}
]
}
{
"type":"CUSTOMER",
"promotionDetails" : {
"programId": 469,
"promotionId":57099
},
"identifierName":"mobile",
"customers":
[ {
"earnIds": [66,67],
"identifierValue":"919986000585",
"source":"INSTORE"
}
]
}
Response parameters
| Parameter | Data Type | Description |
|---|---|---|
response | Array | Contains the list of responses for each entity. |
result | Object | Provides details about the operation performed on a specific entity. |
entityType | String | The type of entity, e.g., "CUSTOMER". |
entityId | Integer | The unique identifier of the entity, e.g., customer ID 98662653. |
promotionId | Integer | The ID of the specific promotion, e.g., 57099. |
programId | Integer | The ID of the loyalty program, e.g., 469. |
revokedEarnIds | Array | List of IDs of earned promotions that are revoked. |
errors | Array | List of errors, if any occurred during the operation (empty in this case). |
warnings | Array | List of warnings, if any occurred during the operation (empty in this case). |
totalCount | Integer | The total number of responses processed, e.g., 1. |
failureCount | Integer | The total number of failures, e.g., 0. |
{
"response": [
{
"result": {
"entityType": "CUSTOMER",
"entityId": 98662653,
"promotionId": 57099,
"programId": 469,
"revokedEarnIds": [
32,
34,
35,
36,
38,
39,
40,
41
]
},
"errors": [],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 0
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8892,
"message": "promotion is inactive"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "Customer not found for the given identifiers",
"code": 8015
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 1101,
"message": "invalid programId passed"
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "promotion id passed is invalid",
"code": 8874
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"message": "Cannot enrol/issue to the user group",
"code": 8899
}
],
"warnings": []
}
],
"totalCount": 1,
"failureCount": 1
}
{
"response": [
{
"errors": [
{
"status": false,
"code": 8902,
"message": "revoke bulk action passed not supported for loyalty/generic promotion type"
}
],
"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
}
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. |
| 8902 | Revoke bulk action passed not supported for loyalty/generic promotion type |
| 8881 | Insufficient parameters passed; program ID and one of the promotion ID/identifiers are required |
| 8903 | Earn IDs passed are either invalid or already revoked |
| 2305 | Active issued promotion is not available for the customer. |