Developer Documentation

Revoke Issued Promotions

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

This API is used to revoke issued promotions to customers.

📘

Note

This API applies to LOYALTY and 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.capillarytech.com/v2/promotion/bulk/revokeDirectEarn

Prerequisites

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

Resource information

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

Body parameters

ParameterData TypeDescription
type*StringIndicates the entity type. Only the "CUSTOMER" entity is supported (Case sensitive).
promotionDetails*ObjectContains details about the promotion and program.
programId*IntegerThe ID of the loyalty program.
promotionId*IntegerThe ID of the specific promotion.
identifierName*StringThe identifier type for the customer. Supported identifiers: "id" (customer ID), "mobile", and "email".
customersArrayList 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.
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.
identifierValue*StringThe specific identifier value for the identifier type defined in the identifierName.
source*StringThe 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

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 of issued promotions that are revoked.
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": [
                    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 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
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!