Alternate Currency Based Target Group API

Alternate currencies are a flexible rewards system functioning like points but customized to brand-specific needs (e.g., stars or custom coins). A target group based on alternate currencies tracks the alternate currencies earned by customers and rewards them upon reaching the target.

For more information, see the alternate currencies documentation.

Prerequisites

Authentication: Basic or OAuth
Default access group

Resource Information

Parameter	Value
URI	`v3/targetGroups`
HTTP Method	POST
Pagination	No
Rate Limit	No
Batch Support	No

API Endpoint Example

https://eu.api.capillarytech.com/v3/targetGroups

Request body

{
    "active": true,
    "description": "alternate currency target ",
    "name": "alternatecuurency_target",
    "preferredTillId": 50155487,
    "trackingType": "DEFAULT",
    "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
    "totalPeriods": 2,
    "frequencyType": "DAILY",
    "frequency": 0,
    "recurringCycles": 0,
    "periods": [
        {
            "active": true,
            "description": "p1",
            "endDate": "2024-10-24T23:59:00.000",
            "periodStatus": "RUNNING",
            "refCode": 1720782952,
            "startDate": "2024-10-24T00:00:00.000"
        },
        {
            "active": true,
            "description": "p2",
            "endDate": "2024-10-25T23:59:00.000",
            "periodStatus": "NOT_STARTED",
            "refCode": "firstperiod",
            "startDate": "2024-10-25T00:01:00.000"
        }
    ],
    "targets": [
        {
            "active": true,
            "description": "",
            "expression": "true",
            "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
            "filters": [],
            "name": "alternatecuurency_target",
            "targetEntity": "ALTERNATE_CURRENCIES",
            "enrolmentMethod": "IMPORT",
            "targetType": "ALL",
            "defaultValues": [
                {
                    "defaultValue": 20
                },
                {
                    "defaultValue": 20
                }
            ],
            "extendedFieldInfo": {
                "alternateCurrencyIdentifier": "0nzyDx",
                "programId": 46
            }
        }
    ]
}

Request Body Parameters

Parameter Name (Fields marked with are mandatory)*	Data Type	Description
active	Boolean	Indicate if target tracking is active. Default value: `true`
description	String	Brief description of the target group. The character limit for the description is 255 characters and special characters are supported.
name*	String	Name for the target group. The name can be up to 200 characters long, supports special characters, and is case-insensitive.
preferredTillId	Integer	Identifier for the preferred or primary POS till for the target. Note: All alternate currencies allocated for a milestone achievement will be tagged to the preferred till.
trackingType*	Enum	Type of tracking the milestone is created for. Supported values: `DEFAULT`: Track a single target `STREAK`: Track multiple targets as a streak. `CAPPING`: Track the number of points a user has got over a period, so that capping can be applied. Creating a target based on alternate currencies is not supported for unified targets. Refer to the documentation on milestones, unified targets, streaks, and capping for more information.
targetEvaluationType*	Enum	Defines the type of time frame used for evaluating the target. Supported values: `FIXED_CALENDAR_WINDOW:` Each cycle runs for a fixed, predefined time period (for example, one month or one year) from the selected start date. `CYCLIC_WINDOW:` Each cycle can have individual time periods. `PERIOD_AGNOSTIC_WINDOW:` The cycle ends as soon as the user achieves the target, regardless of the time taken. There’s no set time frame for the cycle. Refer to the documentation on milestone cycles for more details.
totalPeriods*	Integer	Total number of period cycles for the target group.
frequencyType*	Enum	Frequency of each cycle in which the user has to achieve the target value. Supported values: `MONTHLY`, `QUARTERLY`, `HALF_YEARLY`, `YEARLY`, `WEEKLY`, `DAILY`, `CUSTOM`.
frequency*	Integer	Number of units corresponding to the selected `frequencyType` For example: If `frequencyType` is `DAILY` and frequency is `10`, the cycle spans ten days.
recurringCycles*	Integer	Total number of cycles defined for the target group. Once a cycle is complete, the target is reset for the new cycle. A maximum of 100 cycles can be defined for a target group.
periods	Object	An object containing details on the target period creation, updates, and time-frame.
active	Boolean	Indicate if the period is active. Default value: `true`
description	String	Brief description of the period. The character limit for the description is 255 characters and special characters are supported.
endDate*	String	End date and time of the period in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Example: `2024-10-24T23:59:00.000`.
periodStatus	Enum	Indicate if the cycle of the Milestone is running or upcoming. Supported values: `RUNNING`, `UPCOMING`, `NOT_STARTED`, `LIVE`, `ENDED`.
refCode*	String	A reference code for the period.
startDate*	String	Start date and time of the period in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Example: `2024-10-24T00:00:00.000`
targets	Object	An object containing details on the targets in the target group.
active	Boolean	Indicate if the target is active. Default value: `true`
description	String	Brief description of the target. The character limit for the description is 255 characters and special characters are supported.
expression	Boolean	Indicate if the target has an expression for evaluation. Default value: `true`
expressionJson	String	A JSON expression that specifies the conditions required to achieve the target. The expression is generated in the backend.
filters	Object	An object containing details on the scope filters active on the target.
name*	String	Name for the target. The name can be up to 200 characters long, supports special characters, and is case-insensitive.
targetEntity*	Enum	KPI on which the target is tracked. For alternate currencies, the value is `ALTERNATE_CURRENCIES`.
enrolmentMethod	Enum	Method of enrolment for the target. Supported values: `TRANSACTION`, `IMPORT`.
targetType*	Enum	Type of target Supported values: `ALL`: Tracks points earned from both loyalty programs and promotions. `REGULAR`: Tracks only loyalty program points. `PROMOTION`: Tracks only promotional points.
defaultValues	Object	An object containing details of the default values for the target.
-- defaultValue	Float	Default value for the target.
extendedFieldInfo*	Object	An object containing details on the extended field information for the target group.
-- alternateCurrencyIdentifier*	String	Unique identifier of the alternate currency that is generated when creating an alternate currency.
-- programId*	Integer	Unique ID of the loyalty program that includes the alternate currency.

{
    "data": {
        "id": 1635,
        "name": "alternatecuurency_target",
        "active": true,
        "preferredTillId": 50155487,
        "periods": [
            {
                "id": 9022,
                "attribution": {
                    "createdOn": "2024-11-22T05:07:09.000+0000",
                    "lastUpdatedOn": "2024-11-22T05:07:09.000+0000",
                    "lastUpdatedBy": {
                        "id": 75140757,
                        "code": "naman",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75140757,
                        "code": "naman",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    }
                },
                "startDate": "2024-10-24",
                "endDate": "2024-10-24",
                "refCode": "1720782952",
                "periodStatus": "ENDED",
                "targetGroupId": 1635,
                "description": "p1",
                "active": true
            },
            {
                "id": 9023,
                "attribution": {
                    "createdOn": "2024-11-22T05:07:09.000+0000",
                    "lastUpdatedOn": "2024-11-22T05:07:09.000+0000",
                    "lastUpdatedBy": {
                        "id": 75140757,
                        "code": "naman",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75140757,
                        "code": "naman",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    }
                },
                "startDate": "2024-10-25",
                "endDate": "2024-10-25",
                "refCode": "vbnmihffgnkji",
                "periodStatus": "ENDED",
                "targetGroupId": 1635,
                "description": "p2",
                "active": true
            }
        ],
        "totalPeriods": 2,
        "description": "streak group",
        "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
        "recurringCycles": 0,
        "frequency": 0,
        "targetCycleStartDate": "2024-10-24T00:00:00.000Z",
        "targetCycleEndDate": "2024-10-25T23:59:59.000Z",
        "frequencyType": "DAILY",
        "trackingType": "DEFAULT",
        "targets": [
            {
                "id": 1912,
                "attribution": {
                    "createdOn": "2024-11-22T05:07:08.885+0000",
                    "lastUpdatedOn": "2024-11-22T05:07:08.885+0000",
                    "lastUpdatedBy": {
                        "id": 75140757,
                        "code": "naman",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75140757,
                        "code": "naman",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    }
                },
                "name": "alternatecuurency_target",
                "targetType": "ALL",
                "targetEntity": "ALTERNATE_CURRENCIES",
                "eventName": "TransactionAdd",
                "targetGroupId": 1635,
                "description": "strnbeasdwascs9",
                "active": true,
                "expression": "true",
                "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
                "filters": [],
                "enrolmentMethod": "IMPORT",
                "defaultValues": [
                    {
                        "id": 11954,
                        "periodId": 9022,
                        "defaultValue": 20
                    },
                    {
                        "id": 11955,
                        "periodId": 9023,
                        "defaultValue": 20
                    }
                ],
                "targetPeriodDefaultValuesMap": {
                    "9022": {
                        "id": 11954,
                        "periodId": 9022,
                        "defaultValue": 20
                    },
                    "9023": {
                        "id": 11955,
                        "periodId": 9023,
                        "defaultValue": 20
                    }
                },
                "extendedFieldInfo": {
                    "programId": 46,
                    "alternateCurrencyIdentifier": "0nzyDx"
                }
            }
        ],
        "leaderboardEnabled": false,
        "userCreated": false
    },
    "errors": null,
    "warnings": null
}

{
    "data": null,
    "errors": [
        {
            "code": 310033,
            "message": "Invalid target entity and target type combination"
        }
    ],
    "warnings": null
}

{
    "data": null,
    "errors": [
        {
            "code": 310146,
            "message": "Invalid program id"
        }
    ],
    "warnings": null
}

{
    "data": null,
    "errors": [
        {
            "code": 310094,
            "message": "Target rule metadata is required in case of EXTENDED_FIELD/ALTERNATE_CURRENCIES target type"
        }
    ],
    "warnings": null
}

{
    "data": null,
    "errors": [
        {
            "code": 310147,
            "message": "Invalid or null Alternate Currency Identifier for target rule"
        }
    ],
    "warnings": null
}

Response parameters

Parameter	Data Type	Description
`id`	Integer	Unique ID of the target group.
`name`	String	Unique name of the target group.
`active`	Boolean	Indicates if target tracking is active.
`preferredTillId`	Integer	Identifier for the preferred or primary POS till for the target. Note: All alternate currencies allocated for a milestone achievement will be tagged to the preferred till.
`periods`	Object	An object containing details on target creation, updates, and time-frame.
`periods.id`	Integer	Unique ID of the target period.
`periods.attribution`	Object	An object containing details on the creation and update details of the target period.
`periods.attribution.createdOn`	String	Date the target period was created in ISO 8601 format. Example: `2024-12-10T11:49:28.972+0000`
`periods.attribution.lastUpdatedOn`	String	Date the target period was last updated in ISO 8601 format. Example: `2024-12-10T11:49:28.972+0000`
`periods.attribution.lastUpdatedBy`	Object	An object containing details on the updates to the target period.
`periods.attribution.lastUpdatedBy.id`	Integer	Unique ID of the user who last modified the target period.
`periods.attribution.lastUpdatedBy.code`	String	Code of the user who last modified the target period.
`periods.attribution.lastUpdatedBy.description`	String	Description of the user who last modified the target period.
`periods.attribution.lastUpdatedBy.name`	String	Name of the user who last modified the target period.
`periods.attribution.lastUpdatedBy.type`	String	Type of user who last modified the target period.
`periods.startDate`	String	Start date of the target group in `YYYY-MM-DD`. Example: `2024-10-24`
`periods.endDate`	String	End date of the target group in `YYYY-MM-DD`. Example: `2024-10-24`
`periods.refCode`	Integer	Custom identifier used to identify a target.
`periods.periodStatus`	Enum	Status of the target period: `RUNNING`, `UPCOMING`, `NOT_STARTED`, `LIVE`, `ENDED`.
`periods.targetGroupId`	Integer	Unique ID of the target group.
`periods.description`	String	Description of the target group.
`periods.active`	Boolean	Status of the target period: true (active) or false (inactive).
`totalPeriods`	Integer	Total number of periods for the target group.
`description`	String	Description of the target period.
`targetEvaluationType`	Enum	Evaluation type: `FIXED_CALENDAR_WINDOW`, `CYCLIC_WINDOW`, `PERIOD_AGNOSTIC_WINDOW`.
`recurringCycles`	Integer	Number of cycles for the target group (max: 100).
`frequency`	Integer	Units per selected `frequencyType`.
`targetCycleStartDate`	String	Start of the target cycle in ISO 8601 format.
`targetCycleEndDate`	String	End of the target cycle in ISO 8601 format.
`frequencyType`	Enum	Frequency of target cycles: `MONTHLY`, `QUARTERLY`, `HALF_YEARLY`, `YEARLY`, `WEEKLY`, `DAILY`, `CUSTOM`.
`trackingType`	Enum	Milestone tracking type: `DEFAULT`, `STREAK`, `CAPPING`.
`targets`	Object	Details on targets in the target group.
`targets.id`	Integer	Unique ID of the target.
`targets.attribution.createdOn`	String	Target creation date in ISO 8601.

API error codes

Code	Description
310069	Target group name already exists
300004	Invalid input, check all values and ensure they are correct.
310008	Length of Target rule name cannot exceed 200
310033	Invalid target entity and target type combination
310146	Invalid program id
310094	Target rule metadata is required in case of EXTENDED_FIELD/ALTERNATE_CURRENCIES target type
310147	Invalid or null Alternate Currency Identifier for target rule