Developer Documentation

(Bulk)Enrol Customers to a Promotion

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 customers to a promotion in bulk to customers. You can also use this API to issue a single promotion.

📘

Note

This API is used to enrol multiple customers a single promotion. You cannot use this API to 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 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://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

URIpromotion/bulk/enrolAndEarn
HTTP methodPOST
Pagination supported?NA
Rate limitNA
Batch supportNA

Body parameters

ParameterData TypeDescription
typeEnumIndicates the entity type. Only the "CUSTOMER" entity is supported (Case sensitive).
bulkActionEnumThe bulk action to be performed. Use "ENROL" to enrol customers in a promotion.
promotionDetailsObjectDetails of the promotion to enrol the customer in.
programIdIntegerThe ID of the loyalty program.
promotionIdIntegerThe ID of the specific promotion.
identifierNameEnumThe 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.
identifierValueStringThe specific identifier value for the identifier type defined in the identifierName.
sourceEnumThe source of the customer's registration, e.g., "INSTORE".
{
    "type" : "CUSTOMER",
    "bulkAction" : "ENROL",
    "promotionDetails" : {
       "programId": 469, 
       "promotionId":57099
    },
    "identifierName":"id",
    "customers":
    [   
        {
            "identifierValue":"555567088",
            "source":"INSTORE"
        }
    ]
}

{
    "type" : "CUSTOMER",
    "bulkAction" : "ENROL",
    "promotionDetails" : {
       "programId": 469, 
       "promotionId":69218
    },
    "identifierName":"mobile",
    "customers":
    [   
        {
            "identifierValue":"11223569865",
            "source":"INSTORE"
        },
        {
            "identifierValue":"919986000586",
            "source":"INSTORE"
        }
    ]
}

Response parameters

ParameterData TypeDescription
responseArrayList of response objects.
resultObjectContains the result details for each entity.
entityTypeStringThe type of the entity.
entityIdIntegerThe unique identifier of the entity.
promoIdentifierStringThe identifier for the promotion.
programIdIntegerThe ID of the program associated with the promotion.
issualIdStringThe unique ID of the program generated when the customer is enrolled to a promotion
errorsArrayList of errors encountered.
warningsArrayList of warnings encountered.
totalCountIntegerThe total count of successful responses.
failureCountIntegerThe count of failed responses.
{
    {
    "response": [
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 555567088,
                "promotionId": 57099,
                "programId": 469,
                "issualId": "63"
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

{
    "response": [
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 555567088,
                "promotionId": 69218,
                "programId": 469,
                "issualId": "66"
            },
            "errors": [],
            "warnings": []
        },
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 554537019,
                "promotionId": 69218,
                "programId": 469,
                "issualId": "67"
            },
            "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 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.
8881Insufficient parameters passed; program ID and one of the promotion ID/identifiers are required
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!