Get Loyalty Promotion Benefits for Customer

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.

👍

Note

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 .

Prerequisites

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

Resource Information

URI/v2/customers/lookup/customerPromotionDetails/actionSummary
HTTP methodGET
PaginationNo. Sorting is not supported.
Rate limitNA
Batch supportNA

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 8601YYYY-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 8601YYYY-MM-DDTHH:mm:ss+HH:mm format.

warnings

Object containing warnings, if any.

API Specific Error Codes

Error CodeDescriptionReason
8116No 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)
8874Promotion id passed is invalidThe provided promotionId or promotionIdentifier does not exist or is invalid.
8015Customer not found for the given identifiersNo customer matches the provided identifierName and identifierValue.
8883Insufficient parameters passedprogramId or one of promotionId/promotionIdentifier is missing.
8105Error fetching promotion dataAn 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!