Enrol/Issue Loyalty Promotion

Enrol a customer or issue a promotion to a customer

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.

Terminologies

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

UI/Frontend terminologyBackend terminologyDescription
EnrolIssueEnrol 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.
IssueEarnIssue 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 IssueLOYALTY_EARNING or ISSUE_AND_EARNCustomers must first opt-in or enrol, then achieve the criteria to earn a promotion.
Direct IssueLOYALTY or DIRECTCustomers 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

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

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
}

API-specific error codes

Error CodeDescriptionReason
8892Promotion is inactivePromotion is currently inactive.
8015Customer not found for the given identifiersCustomer is not part of the loyalty program or the customer ID is invalid.
1101Invalid programId passedProgram ID is invalid.
8874Promotion ID passed is invalidPromotion ID is invalid.
8899Cannot enrol/issue to the user group.A user group cannot be enrolled to a promotion.
8881Insufficient parameters passed; program ID and one of the promotion ID/identifiers are requiredRequired parameters are not passed.
8901invalid entity type passedThe entity type is invalid or unsupported.
11013identifierName, identifierValue, source can not be emptyThe fields mentioned are invalid or empty.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!