This API is used to:

Enrol in promotion of type enrol & issue (single/bulk)
Issue promotion of type enrol & issue (single/bulk)
Issue promotion of type Direct Issue (single/bulk)

Refer to the documentation on loyalty promotions for more information on the types of loyalty promotions.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/promotion/bulk/enrolAndEarn' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic a2F2eWNWJkMDI=' \
--data '{
    "type" : "CUSTOMER",
    "bulkAction" : "ENROL",
    "promotionDetails" : {
       "programId":973, 
       "promotionId":109207
    },
    "identifierName":"id",
    "customers":
    [   
        {
            "identifierValue":"565039506",
            "source":"INSTORE"
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/promotion/bulk/enrolAndEarn' \
--header 'accept: application/json' \
--data '{
    "type": "CUSTOMER",
    "bulkAction": "ENROL",
    "promotionDetails": {
        "programId": 973,
        "promotionId": 109321
    },
    "identifierName": "id",
    "customers": [
        {
            "identifierValue": "565039506",
            "source": "INSTORE"
        },
        {
            "identifierValue": "566135941",
            "source": "INSTORE"
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/promotion/bulk/enrolAndEarn' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWFkaMjU2YQ==' \
--header 'Cookie: _cfuvid=lIKWwr1IxaAa4jkFd2fvOvRyW9neDSTT0P4G9bObjY8-1760432725245-0.0.1.1-604800000' \
--data '{
    "type" : "CUSTOMER",
    "bulkAction" : "EARN",
    "promotionDetails" : {
       "programId": 973, 
       "promotionId":57099
    },
    "identifierName":"id",
    "customers":
    [   
        {
            "identifierValue":"98662653",
            "source":"INSTORE"
        }
    ]
}'

curl --location --globoff '{{url}}/v2/promotion/bulk/enrolAndEarn' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bG9jYWMTUyZDIzNGI3MA==' \
--data '{
    "type": "CUSTOMER",
    "bulkAction": "EARN",
    "promotionDetails": {
        "programId": 2714,
        
        "promotionId": 202188
    },
    "identifierName": "id",
    "customers": [
        {
            "identifierValue": "423926199",
            "source": "instore"
        },
        {
            "identifierValue": "423926198",
            "source": "instore"
        },
        {
            "identifierValue": "423926200",
            "source": "instore"
        },
        {
            "identifierValue": "423926201",
            "source": "instore"
        }
    ]
}'

Terminologies

The table below highlights the UI/frontend terminologies and their corresponding backend terms for enrolling and issuing promotions to a customer.

UI/Frontend terminology	Backend terminology	Description
Enrol	Issue	Enrol a customer into a promotion. After enrolment, a promotion must be issued making the customer eligible to earn benefits upon meeting the defined criteria. A customer must be enrolled to the promotion and then issued the promotion in an Enrol and Issue type promotion.
Issue	Earn	Issue a promotion to a customer. Once issued, the customer is eligible to earn benefits upon meeting the defined criteria. A customer can be directly issued a promotion in a Direct Issue type promotion.
Enrol and Issue	`LOYALTY_EARNING` or `ISSUE_AND_EARN`	Customers must first opt-in or enrol, then achieve the criteria to earn a promotion.
Direct Issue	`LOYALTY` or `DIRECT`	Customers directly earn a promotion once they achieve the criteria

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
Loyalty programId and promotionId

Resource information


URI	/v2/promotion/bulk/enrolAndEarn
HTTP method	POST
Pagination supported?	NA
Rate limit	NA
Batch support	Yes

Body parameters

Parameter (Parameters marked as * are required)	Data Type	Description
type*	Enum	Type of entity. Supported entity `CUSTOMER`
bulkAction	Enum	Action to be performed. Supported values: `ENROL`: Enrol customers to a loyalty promotion. `EARN`: Issue a loyalty promotion to customer on completion of activity. Refer to the Supported Actions section for the bulk actions available for each type of promotion.
promotionDetails	Object	Details of the promotion where the action is performed.
programId*	Integer	Unique ID of the loyalty program.
promotionId	Integer	Unique ID of the loyalty promotion. Either `promotionId` or `promoIdentifier` must be provided.
promoIdentifier	String	Unique external identifier of the promotion that is configured. Either `promotionId` or `promoIdentifier` must be provided.
identifierName*	Enum	The identifier type for the customer. Supported identifiers: `id` (customer ID), `mobile`, and `email`.
customers	Object	List of customers on whom the action will be performed. You can add a maximum of 100 customers at once.
identifierValue*	String	Identifier value for the identifier type defined in `identifierName`. Note: The identifier values must be of the same type defined in `identifierName`. For example, if the `identifierName` is `id`, all the `identifierValues` provided must be customer IDs.
source	Enum	The source of the customer's registration. Supported values: `FACEBOOK`, `WEB_ENGAGE`, `INSTORE`, `MARTJACK`, `TMALL`, `TAOBAO`, `JD`, `ECOMMERCE`, `WEBSITE`, `LINE`, `ALL`.

{
    "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"
    }
]
}

{
"type" : "CUSTOMER",
"bulkAction" : "EARN",
"promotionDetails" : {
   "programId": 469,
   "promotionId":57099
},
"identifierName":"id",
"customers":
[
    {
        "identifierValue":"555567088",
        "source":"INSTORE"
    }
]
}

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

Supported Action for the Promotion Type

The table below highlights the supported bulkAction for each type of promotion.

Promotion Type	Supported Bulk Action	Example
Enrol and Issue	`ENROL`	A customer is enrolled in a promotion for making a purchase worth ₹5000. If they review the product, they can earn a discount voucher for their next purchase.
`EARN`	If the customer completes the review, they earn the discount coupon.
Direct Issue	`EARN`	A customer is issued a promotion for making five purchases and earns a free item for completing the task.

Response parameters

Parameter	Data Type	Description
response	Array	List of response objects.
result	Object	Contains the details for a customer.
entityType	String	Type of entity. Supported entity `CUSTOMER`
entityId	Integer	Unique identifier of the entity.
promotionId	Integer	Unique ID of the loyalty promotion .
promoIdentifier*	String	Unique external identifier of the loyalty promotion that is configured.
programId	Integer	ID of the loyalty program associated with the promotion.
issualId	String	Unique ID generated when the customer is enrolled to a promotion. Note: If the `bulkAction` is `EARN` for the promotion type `DIRECT`, a dummy `issualId` is generated as this is not required for a `DIRECT` promotion.
earnedId	String	Unique ID generated when the customer is issued a loyalty promotion.
errors	Array	List of errors encountered.
warnings	Array	List of warnings encountered.
totalCount	Integer	Total count of successful responses.
failureCount	Integer	Count of failed responses.

{
    "response": [
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 423926199,
                "promotionId": 202188,
                "programId": 2714,
                "issualId": "847"
            },
            "errors": [],
            "warnings": []
        },
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 423926198,
                "promotionId": 202188,
                "programId": 2714,
                "issualId": "848"
            },
            "errors": [],
            "warnings": []
        },
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 423926200,
                "promotionId": 202188,
                "programId": 2714,
                "issualId": "849"
            },
            "errors": [],
            "warnings": []
        },
        {
            "result": {
                "entityType": "CUSTOMER",
                "entityId": 423926201,
                "promotionId": 202188,
                "programId": 2714,
                "issualId": "850"
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 4,
    "failureCount": 0
}

{
"response": [
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926199,
            "promotionId": 202188,
            "programId": 2714,
            "issualId": "847",
            "earnedId": "840"
        },
        "errors": [],
        "warnings": []
    },
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926198,
            "promotionId": 202188,
            "programId": 2714,
            "issualId": "848",
            "earnedId": "841"
        },
        "errors": [],
        "warnings": []
    },
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926200,
            "promotionId": 202188,
            "programId": 2714,
            "issualId": "849",
            "earnedId": "842"
        },
        "errors": [],
        "warnings": []
    },
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926201,
            "promotionId": 202188,
            "programId": 2714,
            "issualId": "850",
            "earnedId": "843"
        },
        "errors": [],
        "warnings": []
    }
],
"totalCount": 4,
"failureCount": 0
}

{
"response": [
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926199,
            "promotionId": 202090,
            "programId": 2714,
            "issualId": "837", //this is a dummy Id
            "earnedId": "794"
        },
        "errors": [],
        "warnings": []
    },
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926198,
            "promotionId": 202090,
            "programId": 2714,
            "issualId": "838", //this is a dummy Id
            "earnedId": "795"
        },
        "errors": [],
        "warnings": []
    },
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926200,
            "promotionId": 202090,
            "programId": 2714,
            "issualId": "839",
            "earnedId": "796"
        },
        "errors": [],
        "warnings": []
    },
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 423926201,
            "promotionId": 202090,
            "programId": 2714,
            "issualId": "840", //this is a dummy Id
            "earnedId": "797"
        },
        "errors": [],
        "warnings": []
    }
],
"totalCount": 4,
"failureCount": 0
}

{
"response": [
    {
        "errors": [
            {
                "status": false,
                "message": "bulk action passed not supported for loyalty/generic promotion type",
                "code": 8902
            }
        ],
        "warnings": []
    }
],
"totalCount": 1,
"failureCount": 1
}

{
"response": [
    {
        "result": {
            "entityType": "CUSTOMER",
            "entityId": 170940055,
            "promotionId": 74116,
            "programId": 699,
            "issualId": "72",
            "earnedId": "102"
        },
        "errors": [],
        "warnings": []
    },
    {
        "errors": [
            {
                "status": false,
                "code": 8015,
                "message": "Customer not found for the given identifiers"
            }
        ],
        "warnings": []
    },
    {
        "errors": [
            {
                "status": false,
                "code": 8015,
                "message": "Customer not found for the given identifiers"
            }
        ],
        "warnings": []
    },
    {
        "errors": [
            {
                "status": false,
                "code": 8015,
                "message": "Customer not found for the given identifiers"
            }
        ],
        "warnings": []
    }
],
"totalCount": 4,
"failureCount": 3
}

{
"response": [
    {
        "errors": [
            {
                "status": false,
                "message": "invalid programId passed",
                "code": 1101
            }
        ],
        "warnings": []
    }
],
"totalCount": 1,
"failureCount": 1
}

{
"response": [
    {
        "errors": [
            {
                "status": false,
                "message": "promotion is inactive",
                "code": 8892
            }
        ],
        "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,
                "message": "Error occurred while issuing promotion to the customer",
                "code": 8896
            }
        ],
        "warnings": []
    }
],
"totalCount": 1,
"failureCount": 1
}

{
"response": [
    {
        "errors": [
            {
                "status": false,
                "message": "invalid entity type passed",
                "code": 8901
            }
        ],
        "warnings": []
    }
],
"totalCount": 1,
"failureCount": 1
}

Error codes

Error Code	Description
8892	Promotion is inactive. Ensure loyalty promotion is active.
8015	Customer not found for the given identifiers. Provide a valid customer ID.
1101	Invalid programId passed. Provide a valid Program ID.
8874	Promotion ID passed is invalid. Provide a valid Promotion ID.
8899	Cannot enrol/issue to the user group. A user group cannot be enrolled to a promotion.
8881	Insufficient parameters passed; program ID and one of the promotion ID/identifiers are required. Provide a valid `promotionId`.
8901	Invalid entity type passed. Provide a valid entity type.
11013	IdentifierName, identifierValue, source can not be empty
8890	Promotion not issued due to config issues or customer exhausted limits. Check the limits configured for loyalty promotions.
8889	Promotion id is expired. Provide a valid promotion id.
8895	Invalid bulk Action. Provide a valid bulkAction.
8912	Promotion type not supported. Provide a valid promotion type.
2306	MAX_NUMBER_OF_EARNS_PER_CUSTOMER already used by the customer. Check the earn limits for loyalty promotion.
2305	Promotion not issued for the customer because the customer status is suspended. Provide a valid identifier value.
8913	Bulk action passed not supported for loyalty/generic promotion type. Check the promotion type.