A loyalty promotion is a strategy used to reward customers for their engagement and transactions with a brand.

This API retrieves promotion list for a specific customer who is part of a connected organisation. It provides detailed information about the promotions associated with the customer within a loyalty program. This includes the types of promotions, point and redemption restrictions, start and end dates, and activation status.

By default, types of promotions are not available for all organisations. This feature must be enabled separately. For more details on types of promotions, refer to types of promotions.

📘
Note
This API fetches results for loyalty promotions created on the old UI and the new UI.

Types of promotions

There are three different types of promotions:

GENERIC (UI term - Available without issue)
LOYALTY (UI term - Direct issue)
LOYALTY_EARNING (UI term - Enroll & Issue)

The field pointsOfferType in the response provides information on the type of promotion.

API endpoint example

(https://eucrm.cc.capillarytech.com/v2.1/customers/lookup/promotionData?identifierName=mobile&identifierValue=917406400033&source=INSTORE

Prerequisites

Authentication: Basic or OAuth credentials
Access group resource: Read access to customer group resource

Resource information


URI	/v2.1/customers/lookup/promotionData
HTTP Method	GET
Pagination	Yes
Batch support	No

Headers

Header Description

DATA-SCOPE-ORG

List of Organisation IDs

DATA-SCOPE

Scopes define what data can be accessed using the API. You can use scopes to control access to data from a parent or child organisation. Defining a scope ensures that the response contains only data from the respective organisation.

Supported headers: SELF, OTHER and ALL.

Refer to connected orgs data scopes for more information.

Query parameters

Parameter Name	Data Type	Description
identifierName*	String	Identifier of the customer. Supported values `mobile` , `id`, `email` and `externalid`
identifierValue*	Integer	Value for the identifier. For example, the mobile number or customer ID.
source*	String	Source in which the identifier is available. For example, `INSTORE`, `MARTJACK`, `WECHAT`, `FACEBOOK`, `WEB_ENGAGE`, `TMALL`, `TAOBAO`, `JD`, `ECOMMERCE`, `WEBSITE`, `LINE`, `ALL`
promotionStatusForCustomer	String	Provides information about customer enrollment and issuances in the promotion. Supported values are:- `AVAILABLE_TO_ENROL`:- Promotions of the "Enrol & Issue" type that customers can still enroll in. `AVAILABLE_TO_EARN`:- Promotions the customer is eligible to earn, including "Direct Issue" promotions and "Enrol & Issue" promotions where the customer is already enrolled. `AVAILABLE_TO_REDEEM`:- Active promotions that the customer can currently redeem (get benefits) across all types of promotionns including "Enrol & Issue", "Direct Issue" and "Available to Issue" `EXPIRED`:- Promotions that have expired, i.e. promotion's end date is in past.
includeAlternateCurrencyUsage	Boolean	With the parameter, the backend includes alternate currency usage in the same response fields used for points. By default, the value is false.
limit	String	Number of results that need to be displayed. The values from zero to a maximum of 100 are supported.
offset	String	Start index for data retrieval. This value should not be negative.

Response parameters

Parameter	Data Type	Description
pageDetails	Object	Object containing pagination details.
- pageNumber	Integer	Page number of the current result set.
- pageSize	Integer	Number of entries per page.
- totalEntries	Integer	Total number of entries in the result set.
- pageCount	Integer	Total number of pages in the result set.
customerId	Integer	Identifier of the customer.
promotions	Object	An object containing details of promotions.
- promotionId	Integer	Unique identifier for the promotion issued to the customer.
- promotionName	String	Name of the promotion.
- programId	Integer	Identifier of the loyalty program associated with the promotion.
- startDate	String	Start date of the promotion. ISO 8601 Date Format
- endDate	String	End date of the promotion. ISO 8601 Date Format
- identifier	String	Universally Unique Identifier for the promotion.
- description	String	Description of the promotion.
- active	Boolean	Indicates if the promotion is active.
- eventName	String	Event triggering the promotion.
- promotionMetadata	Object	Array containing metadata for the promotion.
- - key	String	Key of the metadata.
- - value	String	Value of the metadata.
- - brandDefined	Boolean	Indicates if the metadata is brand-defined.
- limits	Object	Object containing limits set for the promotion.
- - maxPointsPerEvent	Integer	Maximum number of points offered per event.
- - pointsPerCustomer	Integer	Maximum points a customer can earn.
- - numberOFTimesPerCustomer	Integer	The maximum number of activities per customer that can allocate points.
- - totalPointsInPromotion	Integer	The maximum points permitted across customers within the promotion duration.
- customerUsage	Object	Object containing customer usage details.
- - currentPointsPerCustomer	String	The current points accrued by the customer.
- - currentNumberOfTimesPerCustomer	Integer	The number of activities through which the customer has received the points.
- - currentTotalPointsInPromotion	String	The points received by all customers within the promotion duration.
- pointsOfferType	String	Type of promotion. The types of promotion are GENERIC, LOYALTY, and LOYALTY_EARNING.
- promotionRestriction	Object	Object containing promotion restriction details. You can set limits on how many times a promotion can be issued and redeemed. Information in this field is replicated if Advanced loyalty Promotion is available for your organisation.
- - issualRestrictions	Object	Array containing issual restriction details.
- - - kpi	String	Key performance indicator for the restriction. The KPI values are MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER and MAX_POINTS_PER_ISSUAL_PER_CUSTOMER.
- - - maxLimit	String	Maximum times a customer can be enrolled in a promotion.
- - - currentCustomerUsage	String	The present count of a customer's enrolment in a promotion.
- - - limitOn	String	Specifies what the limit applies to. The values are EVENT, CUSTOMER, or PROMOTION.
- - earnRestrictions	Object	Array containing earn restriction details.
- - - kpi	String	Key performance indicator for the restriction. The KPI values are MAX_NUMBER_OF_EARNS_PER_CUSTOMER and MAX_POINTS_PER_EARN_PER_CUSTOMER.
- - - maxLimit	String	Maximum times a promotion can be issued to a customer.
- - - currentCustomerUsage	String	The present number of instances a promotion is issued to the customer.
- - - limitOn	String	Specifies what the limit applies to. The values are EVENT, CUSTOMER, or PROMOTION.
- - redemptionRestrictions	Object	Array containing redemption restriction details.
- - - kpi	String	Key performance indicator for the restriction. The KPI values are: MAX_ALLOWED_TIMES_PER_CART MAX_ALLOWED_POINTS_PER_CART MAX_ALLOWED_TIMES_PER_CUSTOMER MAX_ALLOWED_EVENTS_PER_CUSTOMER MAX_ALLOWED_POINTS_PER_CUSTOMER MAX_ALLOWED_TIMES_PER_CUSTOMER MAX_ALLOWED_EVENTS_PER_PROMOTION MAX_ALLOWED_POINTS_PER_PROMOTION
- - - maxLimit	String	Maximum number of times the points can be availed.
- - - currentCustomerUsage	String	The present number of points availed by the customer.
- - - limitOn	String	Specifies what the limit applies to. The values are EVENT, CUSTOMER, or PROMOTION.
- - - type	String	Type of restrictions. The values are NON_PERIOD_BASED or PERIOD_BASED.
orgID	Integer	Unique ID of the associated organisation.
warnings	Object	An array containing any warnings.

Sample Response

{
    "pageDetails": {
        "pageNumber": 0,
        "pageSize": 10,
        "totalEntries": 1,
        "pageCount": 1
    },
    "customerId": 347297848,
    "promotions": [
        {
            "promotionId": 1122938,
            "promotionName": "Award50",
            "programId": 1147,
            "startDate": "2024-08-30T00:00:00.000Z",
            "endDate": "2024-09-29T23:59:59.000Z",
            "identifier": "ed64e808-dc10-4784-a752-eb7d8d55c87e",
            "description": "Award 50",
            "active": true,
            "eventName": "TransactionAdd",
            "limits": {
                "maxPointsPerEvent": "0",
                "pointsPerCustomer": "0",
                "numberOFTimesPerCustomer": 0,
                "totalPointsInPromotion": "0"
            },
            "customerUsage": {
                "currentPointsPerCustomer": "50.000",
                "currentNumberOfTimesPerCustomer": 1,
                "currentTotalPointsInPromotion": "0"
            },
            "pointsOfferType": "GENERIC",
            "promotionRestriction": {
                "issualRestrictions": [],
                "earnRestrictions": [],
                "redemptionRestrictions": []
            },
            "orgId": 50405
        }
    ],
    "warnings": []
}

{
    "pageDetails": {
        "pageNumber": 0,
        "pageSize": 10,
        "totalEntries": 1,
        "pageCount": 1
    },
    "customerId": 347297848,
    "promotions": [
        {
            "promotionId": 1122938,
            "promotionName": "Award50",
            "programId": 1147,
            "startDate": "2024-08-30T00:00:00.000Z",
            "endDate": "2024-09-29T23:59:59.000Z",
            "identifier": "ed64e808-dc10-4784-a752-eb7d8d55c87e",
            "description": "Award 50",
            "active": true,
            "eventName": "TransactionAdd",
            "limits": {
                "maxPointsPerEvent": "0",
                "pointsPerCustomer": "0",
                "numberOFTimesPerCustomer": 0,
                "totalPointsInPromotion": "0"
            },
            "customerUsage": {
                "currentPointsPerCustomer": "50.000",
                "currentNumberOfTimesPerCustomer": 1,
                "currentTotalPointsInPromotion": "0"
            },
            "pointsOfferType": "GENERIC",
            "promotionRestriction": {
                "issualRestrictions": [],
                "earnRestrictions": [],
                "redemptionRestrictions": []
            },
            "orgId": 50405
        }
    ],
    "warnings": []
}

{
    "pageDetails": {
        "pageNumber": 0,
        "pageSize": 10,
        "totalEntries": 1,
        "pageCount": 1
    },
    "customerId": 347297848,
    "promotions": [
        {
            "promotionId": 1122938,
            "promotionName": "Award50",
            "programId": 1147,
            "startDate": "2024-08-30T00:00:00.000Z",
            "endDate": "2024-09-29T23:59:59.000Z",
            "identifier": "ed64e808-dc10-4784-a752-eb7d8d55c87e",
            "description": "Award 50",
            "active": true,
            "eventName": "TransactionAdd",
            "limits": {
                "maxPointsPerEvent": "0",
                "pointsPerCustomer": "0",
                "numberOFTimesPerCustomer": 0,
                "totalPointsInPromotion": "0"
            },
            "customerUsage": {
                "currentPointsPerCustomer": "50.000",
                "currentNumberOfTimesPerCustomer": 1,
                "currentTotalPointsInPromotion": "0"
            },
            "pointsOfferType": "GENERIC",
            "promotionRestriction": {
                "issualRestrictions": [],
                "earnRestrictions": [],
                "redemptionRestrictions": []
            },
            "orgId": 50405
        },
        {
            "promotionId": 1122935,
            "promotionName": "Award 100 Points",
            "programId": 1148,
            "startDate": "2024-08-30T00:00:00.000Z",
            "endDate": "2024-09-29T23:59:59.000Z",
            "identifier": "26a1b64a-f61d-4a64-9dd0-f3fe5a25dcf5",
            "description": "Award 100 Points",
            "active": true,
            "eventName": "TransactionAdd",
            "limits": {
                "maxPointsPerEvent": "0",
                "pointsPerCustomer": "0",
                "numberOFTimesPerCustomer": 0,
                "totalPointsInPromotion": "0"
            },
            "customerUsage": {
                "currentPointsPerCustomer": "100.000",
                "currentNumberOfTimesPerCustomer": 1,
                "currentTotalPointsInPromotion": "0"
            },
            "pointsOfferType": "GENERIC",
            "promotionRestriction": {
                "issualRestrictions": [],
                "earnRestrictions": [],
                "redemptionRestrictions": []
            },
            "orgId": 50406
        }
    ],
    "warnings": []
}

API specific error codes

Error	Description
8013	Identifier name missing or incorrect.
8015	Identifier value missing or incorrect.
8003	Source is missing or incorrect.
310144	Connected Orgs not set properly in Headers. Check whether the target organisation is a connected organisation.