post https://{host}/v3/targetGroups
Unified Target Group API
Note
For detailed information about our APIs and for hands-on testing, refer to the documentation in API overview and the step-by-step guide on making your first API call in Make your first API call.
A unified target is a combination of two or more targets within a target group. You can combine individual targets that involve different customer activities and tracking configurations (KPIs). You can also define an overall target that a user must achieve along with the defined targets.
API endpoint example
POST https://eu.api.capillarytech.com/v3/targetGroupsPrerequisites
- Authentication: Basic authentication details
- Access: WRITE access to the target loyalty access group resource
Resource information
| URI | /v3/targetGroups |
| HTTP method | POST |
| Rate limit | N/A |
| Batch support | N/A |
Request body parameters
| Parameter (*required) | Type | Description |
|---|---|---|
| active | Boolean | Indicates whether the group is active. |
| description | String | A brief description of the group. |
| fromDate | String | The start date and time of the target (ISO 8601). |
| name* | String | The name of the target group (max 200 characters). |
| preferredTillId | Integer | The TILL associated with points issued on completing the target. |
| toDate | String | The end date and time of the target (ISO 8601). |
| trackingType* | Enum | Type of activity tracking: UNIFIED, DEFAULT, STREAKS, CAPPING. - UNIFIED: multiple targets in a single milestone. - DEFAULT: single target milestone. - STREAKS: continuous activity streaks. - CAPPING: apply capping on benefits. |
| totalPeriods* | Integer | Total number of periods in the group. |
| frequency* | Integer | Frequency of the target. |
| recurringCycles* | Integer | Number of cycles for CYCLIC_WINDOW or PERIOD_AGNOSTIC_WINDOW. |
| periods | Array | Array of period objects: |
| - active | Boolean | Indicates if the period is active. |
| - description | String | A brief description of the period. |
| - startDate | String | Start date and time (ISO 8601). |
| - endDate | String | End date and time (ISO 8601). |
| - refCode | String | Reference code of the target period. |
| - periodStatus | Enum | Status of the period: RUNNING, ENDED, NOT_STARTED. |
| targets | Array | Array of target objects: |
| - active | Boolean | Indicates if the target is active. |
| - name | String | The name of the target. |
| - description | String | A brief description of the target. |
| - expression | String | A string representation of the target condition rule. |
| - expressionJson | String | A JSON representation of the target's rule. |
| - filters | Array | Array of filter objects: |
| - entityType | Enum | Entity type for the filter: Transaction, Line item, STORE, etc. |
| - entityIds | Array | Array of entity IDs for the filter. |
| - targetEntity | Enum | Entity that defines the target condition: – TRANSACTION, LINEITEM, POINTS, EVENT, ALTERNATE_CURRENCIES, REWARDS. |
| - enrolmentMethod | Enum | Method to enroll: TRANSACTION (auto-enroll on transaction), IMPORT (import custom values). |
| - targetType | Enum | Target type: – Transactional: QUANTITY, SALES, COUNT, VISIT. – Behavioral: EVENT_ATTRIBUTE. |
| - defaultValues | Array | Array of default value objects: |
| - defaultValue | Integer | Default value for the period. |
| combinationType* | Enum | Logical operator between targets: ANY (any one target), ALL (all targets). |
| unifiedTargetExpression | Object | Unified expression for evaluation: |
| - aggregation | Enum | Aggregation type: SUM, COUNT. (Required if used.) |
| - thresholdValue | Integer | Threshold for the unified expression. (Required if aggregation is set.) |
Sample request – Combination type ALL with aggregation
{
"active": true,
"description": "unified group",
"fromDate": "2023-09-25T13:45:12.063Z",
"name": "demo-unified1",
"preferredTillId": 50679771,
"toDate": "2024-10-31T08:41:00.529Z",
"trackingType": "UNIFIED",
"totalPeriods": 1,
"frequency": 0,
"recurringCycles": 0,
"periods": [
{
"active": true,
"description": "p1",
"startDate": "2023-09-25T13:45:12.063Z",
"endDate": "2023-10-31T23:45:12.063Z",
"refCode": "period44",
"periodStatus": "RUNNING"
}
],
"targets": [
{
"active": true,
"description": "uni15",
"expression": "currentTxn.value>500",
"expressionJson": "{...}",
"filters": [{ "entityType": "STORE", "entityIds": [50679757, 50679770] }],
"name": "t4",
"targetEntity": "TRANSACTION",
"enrolmentMethod": "TRANSACTION",
"targetType": "SALES",
"defaultValues": [{ "defaultValue": 2000 }]
},
{
"active": true,
"description": "uni25",
"expression": "true",
"expressionJson": "{...}",
"filters": [{ "entityType": "STORE", "entityIds": [50679757,50679770] }],
"name": "t5",
"targetEntity": "TRANSACTION",
"enrolmentMethod": "TRANSACTION",
"targetType": "SALES",
"defaultValues": [{ "defaultValue": 2000 }]
}
],
"combinationType": "ALL",
"unifiedTargetExpression": { "aggregation": "SUM", "thresholdValue": 5000 }
}Response parameters
| Parameter | Type | Description |
|---|---|---|
| data | Object | Main object containing details. |
| id | Integer | Unique identifier for the target group. |
| name | String | Name of the target group. |
| fromDate, toDate | String | Start/end dates for the group (ISO 8601). |
| active | Boolean | Whether the group is active. |
| preferredTillId | Integer | Identifier of the associated till. |
| periods | Array | Array of period objects (see above). |
| totalPeriods | Integer | Total number of periods. |
| trackingType | String | Activity tracking type: UNIFIED, DEFAULT, STREAKS, CAPPING. |
| targets | Array | Array of target objects (see above). |
| combinationType | String | Logical operator: ANY, ALL. |
| unifiedTargetExpression | Object | Unified expression (see above). |
API error codes
| Code | Description |
|---|---|
| 310069 | Target group name already exists |
| 300004 | Invalid input; check all values and ensure correctness |
| 310008 | Length of target rule name cannot exceed 200 |