Developer Documentation

Bulk Revoke of Enrolled & Issued Promotions

post https://{host}/v2/promotion/bulk/revokeEnrolAndEarn

This API is used to revoke enrolled or issued promotions for customers in bulk. You can also use this API to revoke a single promotion.

📘

Note

This applies only to the LOYALTY_EARNING promotion type.

Terminologies

The table below highlights backend terminologies and their corresponding terms used in the UI/frontend:

UI/Frontend terminologyBackend terminologyDescription
EnrolIssueThe customer is enrolled into a promotion.
IssueEarnThe 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.capillarutech.com/v2/promotion/bulk/revokeEnrolAndEarn

Prerequisites

  • Authentication - Basic or OAuth authentication
  • Access group resource - Write access to customer group resource

Resource information

URIv2/promotion/bulk/revokeEnrolAndEarn
HTTP methodPOST
Pagination supported?NA
Rate limitNA
Batch supportNA

Body parameters

ParameterData TypeDescription
typeStringIndicates the entity type. Only the "CUSTOMER" entity is supported (Case sensitive).
bulkActionStringThe bulk action to be performed. Supported values: "REVOKE_EARN" to revoke earned promotions by the customer and "REVOKE_ISSUAL" to revoke issued promotions to the customer.
promotionDetailsObjectContains details about the promotion and program.
programIdIntegerThe ID of the loyalty program.
promotionIdIntegerThe ID of the specific promotion.
identifierNameStringThe identifier type for the customer. Supported identifiers: "id" (customer ID), "mobile", and "email".
customersArrayList of customers on whom the action will be performed.
earnIdsArrayList 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. This applies to REVOKE_EARN.
identifierValueStringThe specific identifier value for the identifier type defined in the identifierName.
sourceStringThe source of the customer registration, e.g., "INSTORE".
{
    "type":"CUSTOMER",
   "bulkAction":"REVOKE_ISSUAL",
   "promotionDetails" : {
       "programId": , 
       "promotionId":
    },
     "identifierName":"id",
    "customers":
    [   {
            "identifierValue":"98662653",
            "source":"INSTORE"
        },
     {
            "identifierValue":"98662853",
            "source":"INSTORE"
        }
    ]
}

{
    "type":"CUSTOMER",
   "bulkAction":"REVOKE_EARN",
   "promotionDetails" : {
       "programId": 469, 
       "promotionId":57099
    },
     "identifierName":"mobile",
    "customers":
    [   {        
            "identifierValue":"9199860005856",
            "source":"INSTORE"
        }
    ]
}

{
    "type":"CUSTOMER",
   "bulkAction":"REVOKE_EARN",
   "promotionDetails" : {
       "programId": 469, 
       "promotionId":57099
    },
     "identifierName":"mobile",
    "customers":
    [   {
        "earnIds":[76],
            "identifierValue":"9199860005856",
            "source":"INSTORE"
        }
    ]
}

Response parameters

ParameterData TypeDescription
responseArrayContains the list of responses for each entity.
resultObjectProvides details about the operation performed on a specific entity.
entityTypeStringThe type of entity, e.g., "CUSTOMER".
entityIdIntegerThe unique identifier of the entity, e.g., customer ID 98662653.
promotionIdIntegerThe ID of the specific promotion, e.g., 57099.
programIdIntegerThe ID of the loyalty program, e.g., 469.
revokedEarnIdsArrayList of IDs representing revoked promotions, e.g., [31].
errorsArrayList of errors, if any occurred during the operation (empty in this case).
warningsArrayList of warnings, if any occurred during the operation (empty in this case).
totalCountIntegerThe total number of responses processed, e.g., 1.
failureCountIntegerThe total number of failures, e.g., 0.
{
    "response": [
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 98662653,
                "promotionId": 57099,
                "programId": 469,
                "revokedEarnIds": [
                    31
                ]
            },
            "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,
                    "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": 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 CodeDescription
8892Promotion is inactive
8015Customer not found for the given identifiers
1101Invalid programId passed
8874Promotion ID passed is invalid
8899Cannot enrol/issue to the user group. This happens when you define USERGROUP2 as the entity.
8902Revoke bulk action passed not supported for loyalty/generic promotion type
8881Insufficient parameters passed; program ID and one of the promotion ID/identifiers are required
8903Earn IDs passed are either invalid or already revoked
2305Active issued promotion is not available for the customer.
Language
Authorization
Basic
base64
:
URL
Click Try It! to start a request and see the response here!