post https://{host}/v2/promotion/bulk/revokeDirectEarn
This API is used to revoke issued promotions to customers.
Note
This API applies to
LOYALTY
andLOYALTY_EARNING
promotion 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. NOTE: To set a limit on the number of customers that can be added to a promotion, you need to enable the Bulk API Redirection feature. To do this, set BULK_API_REDIRECTION_ENABLED to true. You can then configure the batch size using the BULK_API_BATCH_SIZE_FOR_REDIRECTION environment variable. If not set, the default batch size is 10, meaning up to 10 customers can be added to the same promotion.If BULK_API_REDIRECTION_ENABLED is disabled, there is no limit on the number of customers in the request. |
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":"9866296543",
"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 issued 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. |