post https://{host}/api_gateway/loyalty/v1/programs//cappings
This API is currently under enhancement, so please don't use it. This page will be updated once the API is fully ready to be used.
This API allows you define earning limits for reward currencies (points and alternate currencies). You can also use this API to create a target/milestone and define earning limits on them.
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
- Unique identifier of the loyalty program (programId)
Resource information
| URI | /api_gateway/loyalty/v1/programs/{programId}/cappings |
| HTTP method | POST |
| Pagination | NA |
| Rate limit | NA |
| Batch support | NA |
API endpoint example
http://eu.api.capillarytech.com/api_gateway/loyalty/v1/programs/973/cappings
Path Parameters
| Parameter | Data Type | Description |
|---|---|---|
| programId | Integer | Unique ID of the loyalty program. |
Request body
{
"scope": "INDIVIDUAL_EVENT",
"name": "Capping_NoTarget",
"entity": "POINTS",
"eventName": "TRANSACTION_ADD",
"isActive": true,
"cappingEntityType": "TRANSACTION_ADD",
"propertyValues": "{\"limit\": \"10002\", \"additionalFilters\": null}",
"createdBy": 1824412,
"enrollmentType": "ENROLL_VIA_AUDIENCE",
"cappingFilterMapping": [
{
"eventSubTypeId": 23,
"filterEntityType": "EVENT",
"filterEntityId": 56
}
]
}
{
"scope": "INDIVIDUAL_EVENT",
"name": "Capping_NoTarget",
"entity": "ALTERNATE_CURRENCIES",
"eventName": "TRANSACTION_ADD",
"isActive": true,
"cappingEntityType": "TRANSACTION_ADD",
"propertyValues": "{\"limit\": \"10002\", \"additionalFilters\": null}",
"createdBy": 1824412,
"enrollmentType": "ENROLL_VIA_AUDIENCE",
"entityIdentifier": "0nzyDx",
"cappingFilterMapping": [
{
"eventSubTypeId": 23,
"filterEntityType": "EVENT",
"filterEntityId": 56
}
]
}
{
"scope": "INDIVIDUAL_CUSTOMER",
"name": "PointsCapping",
"entity": "POINTS",
"targetGroups": "{\"active\": true, \"name\": \"CappingTarget\", \"periods\": [{\"refCode\": \"Cycle_1\", \"startDate\": \"2025-02-01\", \"endDate\": \"2025-04-28\"}], \"frequencyType\": \"CUSTOM\", \"trackingType\": \"CAPPING\", \"targetEvaluationType\": \"FIXED_CALENDAR_WINDOW\", \"preferredTillId\": -1, \"targets\": [{\"active\": true, \"name\": \"CappingTarget\", \"targetEntity\": \"POINTS\", \"defaultValues\": [{\"defaultValue\": \"100\"}], \"enrolmentMethod\": \"TRANSACTION\", \"targetType\": \"REGULAR_POINTS\", \"filters\": []}]}",
"eventName": "TRANSACTION_ADD",
"isActive": true,
"cappingEntityType": "TRANSACTION_ADD",
"propertyValues": "{\"limit\": \"10002\", \"additionalFilters\": null}",
"createdBy": {{jp}},
"enrollmentType": "ENROLL_VIA_AUDIENCE",
"cappingFilterMapping": [
{
"eventSubTypeId": 23,
"filterEntityType": "EVENT",
"filterEntityId": 56
}
]
}
{
"scope": "INDIVIDUAL_CUSTOMER",
"name": "AlternateCurrencyCapping",
"entity": "ALTERNATE_CURRENCIES",
"targetGroups": "{\"active\":true,\"name\":\"AlternateCurrencyCappingTG\",\"periods\":[{\"refCode\":\"Cycle_1\",\"startDate\":\"2025-02-01\",\"endDate\":\"2025-04-28\"}],\"frequencyType\":\"CUSTOM\",\"trackingType\":\"CAPPING\",\"targetEvaluationType\":\"FIXED_CALENDAR_WINDOW\",\"preferredTillId\":-1,\"targets\":[{\"active\":true,\"name\":\"AlternateCurrencyCappingTG\",\"targetEntity\":\"ALTERNATE_CURRENCIES\",\"defaultValues\":[{\"defaultValue\":\"100\"}],\"enrolmentMethod\":\"TRANSACTION\",\"targetType\":\"REGULAR\",\"filters\":[],\"extendedFieldInfo\":{\"alternateCurrencyIdentifier\":\"0nzyDx\",\"programId\":46}}]}",
"eventName": "TRANSACTION_ADD",
"isActive": true,
"cappingEntityType": "TRANSACTION_ADD",
"propertyValues": "{\"limit\": \"10002\", \"additionalFilters\": null}",
"createdBy": {{jp}},
"entityIdentifier": "0nzyDx",
"enrollmentType": "ENROLL_VIA_AUDIENCE",
"cappingFilterMapping": [
{
"eventSubTypeId": 23,
"filterEntityType": "EVENT",
"filterEntityId": 56
}
]
}
Request body parameters
| Parameter Name (Parameters marked with * are mandatory ) | Data Type | Description |
|---|---|---|
| scope* | Enum | Level at which limits is applied. Supported values:INDIVIDUAL_EVENT: Limits reward currencies (points or alternate currencies) for a single transaction or behavioural event.INDIVIDUAL_CUSTOMER: Limits reward currencies (points or alternate currencies ) across multiple transactions or behavioural events. |
| name* | String | Unique name for the limits criteria. Maximum character limit: 200 characters, special characters are supported. |
| entity* | Enum | Specifies which reward currency is being limited. Supported values:POINTS: Limit the number of points a customer can earn.ALTERNATE_CURRENCIES: Limit the number of alternate currencies a customer can earn. |
| targetGroups | String (JSON) | Serialised JSON string defining the target group details. This is required when scope=INDIVIDUAL_CUSTOMER. Refer to the documentation for more information on creating points target and alternate currency targets. |
| eventName* | Enum | Define the event that triggers the limits. Supported values:TRANSACTION_ADD |
| isActive | Boolean | Indicate if limiting reward currencies is active or inactive. Supported values:true: Capping is active.false: Capping is inactive. |
| cappingEntityType* | Enum | Specifies where the limits are applied to. Supported values:ALL_EVENTS: Limits reward currencies earned from all events, transactional and behavioural.PROMOTION: Limits reward currencies earned from loyalty promotions.TRANSACTION_ADD: Limits reward currencies earned from transactions. |
| propertyValues* | String (JSON) | Serialised JSON string containing the limits configurations such as reward currency limits and additional filtering rules. The limit field defines the reward currency limit. |
| createdBy* | Long | Unique customer identifier of the user who created the limit rules. |
| entityIdentifier | String | Unique identifier of the alternate currency that is generated when creating an alternate currency. |
| enrollmentType | Enum | Specifies how the customer is enrolled into the target group. Supported values:UPLOAD: Customer details are uploaded and enrolled manually.ENROLL_VIA_AUDIENCE: Customer are enrolled through audience groups. Use this if scope=INDIVIDUAL_CUSTOMER. |
| enrollmentTypeBody | String (JSON) | JSON string containing enrollment configuration details. |
| cappingFilterMapping* | Object | Object containing details of filter configurations that determine when the limits rule applies. |
| - filterEntityType* | Enum | Specifies what the filter applies to. Supported values: EVENT and PROMOTION |
| - eventSubTypeId* | Long | ID of a specific event subtype that the capping applies to. This field is used to track specific variations or subtypes of events like TransactionAdd, PointsRedemption, etc. Refer to the section on event subtype IDs for more information. |
| - filterEntityId* | Integer | ID of the event or promotion being filtered. When filterEntityType is EVENT, the filterEntityId will correspond to a specific event ID.When filterEntityType is PROMOTION, the filterEntityId will correspond to a specific promotion ID. |
Event Subtype IDs
| Category | Event ID | Event Name |
|---|---|---|
| Core Transaction Events | 1 | NewBill |
| 3 | PointsRedemption | |
| 4 | VoucherRedemption | |
| 5 | ReturnBill | |
| 9 | TransactionFinished | |
| 11 | TransactionUpdate | |
| 16 | DelayedAccrual | |
| 19 | GroupTransactionUpdate | |
| 20 | GroupReturnBill | |
| Customer Related Events | 22 | GroupMemberJoin |
| 23 | GroupMemberLeave | |
| 25 | PointsTransfer | |
| 28 | TargetCompleted | |
| 29 | PointsRedemptionReversal | |
| Communication Events | 6 | TrackerConditionSuccess |
| 10 | ReferralPostProcessing | |
| 13 | EmailOpen | |
| 14 | EmailClick | |
| 17 | Scan | |
| Generic/System Events | -1 | CampaignRefereeRedeem |
| CampaignReferralReferrer | ||
| IncomingSms | ||
| PartnerProgramTierUpdate | ||
| PartnerProgramDeLinking | ||
| SlabUpgrade | ||
| SocialConnectUpdate | ||
| VoucherPreRedemption |
Response body
{
"code": null,
"message": "Capping created successfully"
}
Response parameters
| Field | Data Type | Description |
|---|---|---|
| code | Integer | Error code of the response, if any. |
| message | String | Success or error message for the response, if any. |
API error codes
| Code | Description | Reason |
|---|---|---|
| - | Scope must not be null | scope is not provided in the request. |
| - | Name must not be null | name is not provided in the request. |
| - | Entity must not be null | entity is not provided in the request. |
| - | EventName must not be null | eventName is not provided in the request. |
| - | CappingEntityType must not be null | cappingEntityType is not provided in the request. |
| - | PropertyValues must not be null | propertyValues is not provided in the request. |
| - | CreatedBy must not be null | createdBy is not provided in the request. |
| - | CappingFilterMapping must not be null | cappingFilterMapping object is not provided in the request. |
| - | CappingFilterMapping must not be empty | Parameters under cappingFilterMapping are not provided in the request. |
| - | TargetGroups must not be null for INDIVIDUAL_CUSTOMER | targetGroups is not provided in the request. This is required when scope=INDIVIDUAL_CUSTOMER |
| - | enrollmentTypeBody must not be null for AUDIENCE_FILTER | If scope=INDIVIDUAL_CUSTOMER and targetGroup has the AUDIENCE_FILTER parameter, the enrollmentTypeBody JSON string must not be empty. |
| max limit for cart and customer based capping is 50 each | The maximum limit for the number of cappings for cart and customer has exceeded. |