Get Loyalty Promotion Benefits for Customer

get https://{host}/v2/customers/lookup/customerPromotionDetails/actionSummary

This API fetches a consolidated view (summary) of all loyalty promotion benefits—points, alternate currencies, rewards, and badges—that a specific customer has earned for a loyalty promotion.

👍
Notes

For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

This API only lists benefits earned from a promotion on or after June 12, 2025. Any benefits earned before that will not be included.

Prerequisites

Authentication: Basic/OAuth authentication
Default access group
programId and promotionId or promotionIdentifier

Resource Information


URI	/v2/customers/lookup/customerPromotionDetails/actionSummary
HTTP method	GET
Pagination	No. Sorting is not supported.
Rate limit	NA
Batch support	NA

Example API cURL

https://eu.api.capillarytech.com/v2/customers/lookup/customerPromotionDetails/actionSummary?source=INSTORE&identifierName=mobile&identifierValue=919078345795&programId=2568&promotionId=2000065

Query parameters

Parameter Name (Parameters marked as * are required)	Data Type	Description
source*	Enum	Source of customer information. Supported values: `INSTORE`,`FACEBOOK`,`WEB_ENGAGE`,`WECHAT`,`MARTJACK`,`TMALL`,`TAOBAO`,`JD`,`ECOMMERCE`,`WEBSITE`,`LINE`,`MOBILE_APP`
identifierName*	Enum	Identifier type to identify the customer. Supported values: `mobile`, `id`, `externalId`
identifierValue*	String	Value corresponding to the `identifierName` provided.
programId*	Integer	Unique ID of the loyalty program. To retrieve the `programId` , use the Get Loyalty Programs API .
promotionId	String	Unique ID of the loyalty promotion. Required if `promotionIdentifier` is not provided. To retrieve the `promotionId`, use the Get Details of all Promotions API.
promotionIdentifier	String	External identifier for the loyalty promotion. Required if `promotionId` is not provided. To retrieve the `promotionIdentifier`, use the Get Details of all Promotions API.

Response body

{
    "orgId": 51135,
    "programId": 2568,
    "customerId": 387729100,
    "promotionId": 2000065,
    "promotionIdentifier": "021a1876-17d9-4d7a-bd2c-e74a65298398",
    "points": [
        {
            "pointsCategory": "REGULAR_POINTS",
            "totalPointsIssued": 600.000,
            "numberOfTimesIssued": 6,
            "lastIssuedOn": "2025-03-22T17:36:21+05:30"
        },
        {
            "pointsCategory": "PROMISED_POINTS",
            "totalPointsIssued": 600.000,
            "numberOfTimesIssued": 6,
            "lastIssuedOn": "2025-03-22T17:36:21+05:30"
        }
    ],
    "alternateCurrencies": [
        {
            "alternateCurrencyName": "DocCoin",
            "alternateCurrencySubDetails": [
                {
                    "alternateCurrencyType": "REGULAR",
                    "totalIssued": 5600.000,
                    "numberOfTimesIssued": 8,
                    "lastIssuedOn": "2025-03-22T17:36:21+05:30"
                }
            ]
        }
    ],
    "rewards": [
        {
            "rewardSeriesId": "113336.0",
            "numberOfTimesIssued": 2,
            "lastIssuedOn": "2025-03-29T16:30:01+05:30"
        }
    ],
    "badges": [
        {
            "badgeSeriesId": "67ce697296dcfc6386c64f8a",
            "numberOfTimesIssued": 8,
            "lastIssuedOn": "2025-03-22T17:36:23+05:30"
        }
    ],
    "warnings": []
}

{
    "errors": [
        {
            "status": false,
            "code": 8874,
            "message": "promotion id passed is invalid"
        }
    ]
}

{
    "errors": [
        {
            "status": false,
            "code": 8015,
            "message": "Customer not found for the given identifiers"
        }
    ]
}

{
    "errors": [
        {
            "status": false,
            "code": 8883,
            "message": "Insufficient parameters passed, program id and one of promotion id/identifier are required."
        }
    ]
}

{
    "errors": [
        {
            "status": false,
            "code": 8105,
            "message": "Error fetching promotion data. Verify programs/promotionIdentifier passed."
        }
    ]
}

Response parameters

Parameter	Description
orgId	Unique ID of the organization.
programId	Unique ID of the loyalty program.
customerId	Unique ID of the customer.
promotionId	Unique ID of the loyalty promotion.
promotionIdentifier	External identifier of the loyalty promotion.
points	Array containing details about points earned.
pointsCategory	Category of the points issued. Possible values: `REGULAR_POINTS`, `PROMISED_POINTS`, `EXTERNAL_TRIGGER_BASED_POINTS`.
totalPointsIssued	Total number of points issued for the loyalty promotion.
numberOfTimesIssued	Number of times points were issued for the loyalty promotion.
lastIssuedOn	Timestamp of the last time points were issued under this category in ISO 8601 `YYYY-MM-DDTHH:mm:ss+HH:mm` format.
alternateCurrencies	Object containing details about alternate currencies earned.
alternateCurrencyName	Name of the alternate currency.
alternateCurrenciesSubDetails	Object containing details for different types within this alternate currency.
-- alternateCurrencyType	Type of the alternate currency issued. Possible values: `REGULAR`, `PROMISED`, `EXTERNAL_TRIGGER_BASED`.
-- totalIssued	Total amount of this alternate currency type issued for this loyalty promotion.
-- numberOfTimesIssued	Number of times this alternate currency type was issued.
-- lastIssuedOn	Timestamp of the last time this alternate currency type was issued in ISO 8601 `YYYY-MM-DDTHH:mm:ss+HH:mm` format.
rewards	Object containing details about rewards earned.
rewardSeriesId	Unique identifier for the reward series.
numberOfTimesIssued	Number of times the reward was issued.
lastIssuedOn	Timestamp of the last time this reward was issued in ISO 8601`YYYY-MM-DDTHH:mm:ss+HH:mm` format.
badges	Object containing details about badges earned.
badgeSeriesId	Unique identifier for the reward series.
numberOfTimesIssued	Number of times the badge was issued.
lastIssuedOn	Timestamp of the last time this badge was issued in ISO 8601`YYYY-MM-DDTHH:mm:ss+HH:mm` format.
warnings	Object containing warnings, if any.

API Specific Error Codes

Error Code	Description	Reason
8116	No benefits earned by customer for the given promotion.	The API call was successful, but the customer hasn't received any benefits yet. (Returned in warnings)
8874	Promotion id passed is invalid	The provided `promotionId` or `promotionIdentifier` does not exist or is invalid.
8015	Customer not found for the given identifiers	No customer matches the provided `identifierName` and `identifierValue`.
8883	Insufficient parameters passed	`programId` or one of `promotionId`/`promotionIdentifier` is missing.
8105	Error fetching promotion data	An internal error occurred while retrieving promotion details (e.g., thrift call failed).

Language

Credentials

Basic

base64

URL

Click Try It! to start a request and see the response here!