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.

Example request

curl -L 'https://eu.api.capillarytech.com/v3/targetGroups' \
-H 'Content-Type: application/json' \
-H 'Cookie: _cfuvid=aidEostKQWmdskBHmh1pchvz2wSoA1O27JghNUFOpHw-1728306311172-0.0.1.1-604800000; _cfuvid=2ieM2eqBqFdNAAdfQMYR0zNvTd6WWmQxVVyU.OyFiEw-1728475108732-0.0.1.1-604800000; _cfuvid=kYnuHywd2SuhkmuOi2_c7.Ie8_QvI8s1bFiaSPpP.8M-1759827226073-0.0.1.1-604800000; _cfuvid=4yQ.rawpbQf4P30QMM55R316xFW18w5eFCc.rEOnRfQ-1764071843446-0.0.1.1-604800000' \
-H 'Authorization: Basic ZlY2I2MmEy' \
-d '{
    "active": true,
    "fromDate": "2025-10-07T00:00:00.529Z",
    "name": "uatTargetGroup96",
    "preferredTillId": 75155297,
    "toDate": "2025-11-25T00:00:00.529Z",
    "trackingType": "DEFAULT",
    "timeZoneName": "Asia/Kolkata",
    "totalPeriods": 2,
    "frequency": 2,
    "recurringCycles": 2,
    "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
    "targetCycleStartDate": "2025-07-23T00:00:00.529Z",
    "periods": [
        {
            "active": true,
            "description": "p1",
            "endDate": "2025-07-21T23:00:00.529Z",
            "periodStatus": "RUNNING",
            "refCode": "Cycle_1",
            "startDate": "2025-07-21T00:00:00.529Z"
        },
        {
            "active": true,
            "description": "p2",
            "endDate": "2025-07-23T00:00:00.529Z",
            "periodStatus": "NOT_STARTED",
            "refCode": "Cycle_2",
            "startDate": "2025-07-22T00:00:00.529Z"
        }
    ],
    "targets": [
        {
            "targetEntity": "ALTERNATE_CURRENCIES",
            "targetType": "ALL",
            
            "extendedFieldInfo": {
                "alternateCurrencyIdentifier": "DocCoin",
                "programId": 783
            },
            "defaultValues": [
                {
                    "defaultValue": "2"
                },
                {
                    "defaultValue": "3"
                }
            ],
            "targetMilestoneTriggers": [],
            "expression": "true",
            "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
            "filters": [],
            "name": "uat_target_group_96",
            "enrolmentMethod": "IMPORT"
        }
    ]
}'

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

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.
timeZoneName	String	IANA time zone name for the target group; defaults to system time zone when omitted.
targetCycleStartDateISO	String	Defines the target’s start date in ISO 8601 format with the region offset. For example: The start date is at 14:30:45 on December 16, 2025, in India Format for the request parameter: 2025-12-16T14:30:45+05:30
targetCycleEndDateISO	String	Defines the target’s end date in ISO 8601 format with the region offset. For example: The start date is at 14:30:45 on December 16, 2025, in India Format for the request parameter: 2025-12-16T14:30:45+05:30
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.

Example response

{
    "data": {
        "id": 2909,
        "name": "uatTargetGroup132",
        "fromDate": "2026-01-01",
        "toDate": "2026-02-01",
        "active": true,
        "preferredTillId": 75155297,
        "periods": [
            {
                "id": 31619,
                "attribution": {
                    "createdOn": "2026-01-12T12:09:28.000+0000",
                    "createdOnISO": "2026-01-12T12:09:28Z",
                    "lastUpdatedOn": "2026-01-12T12:09:28.000+0000",
                    "lastUpdatedOnISO": "2026-01-12T12:09:28Z",
                    "lastUpdatedBy": {
                        "id": 75152721,
                        "code": "naman_doc",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75152721,
                        "code": "naman_doc",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    }
                },
                "startDate": "2025-07-21",
                "endDate": "2025-07-21",
                "refCode": "Cycle_1",
                "periodStatus": "ENDED",
                "targetGroupId": 2909,
                "description": "p1",
                "active": true
            },
            {
                "id": 31620,
                "attribution": {
                    "createdOn": "2026-01-12T12:09:28.000+0000",
                    "createdOnISO": "2026-01-12T12:09:28Z",
                    "lastUpdatedOn": "2026-01-12T12:09:28.000+0000",
                    "lastUpdatedOnISO": "2026-01-12T12:09:28Z",
                    "lastUpdatedBy": {
                        "id": 75152721,
                        "code": "naman_doc",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75152721,
                        "code": "naman_doc",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    }
                },
                "startDate": "2025-07-22",
                "endDate": "2025-07-23",
                "refCode": "Cycle_2",
                "periodStatus": "ENDED",
                "targetGroupId": 2909,
                "description": "p2",
                "active": true
            }
        ],
        "totalPeriods": 2,
        "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
        "recurringCycles": 2,
        "frequency": 2,
        "targetCycleStartDate": "2025-07-23T00:00:00.529Z",
        "targetCycleEndDate": "2026-02-01T05:00:00.000Z",
        "targetCycleStartDateISO": "2025-07-23T00:00:00Z",
        "targetCycleEndDateISO": "2026-02-01T05:00:00Z",
        "trackingType": "DEFAULT",
        "targets": [
            {
                "id": 3146,
                "attribution": {
                    "createdOn": "2026-01-12T12:09:27.605+0000",
                    "createdOnISO": "2026-01-12T12:09:27Z",
                    "lastUpdatedOn": "2026-01-12T12:09:27.605+0000",
                    "lastUpdatedOnISO": "2026-01-12T12:09:27Z",
                    "lastUpdatedBy": {
                        "id": 75152721,
                        "code": "naman_doc",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    },
                    "createdBy": {
                        "id": 75152721,
                        "code": "naman_doc",
                        "description": "",
                        "name": "naman",
                        "type": "TILL"
                    }
                },
                "name": "uat_target_group_132",
                "targetType": "ALL",
                "targetEntity": "ALTERNATE_CURRENCIES",
                "eventName": "TransactionAdd",
                "targetGroupId": 2909,
                "active": true,
                "expression": "true",
                "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
                "filters": [],
                "enrolmentMethod": "IMPORT",
                "defaultValues": [
                    {
                        "id": 128499,
                        "periodId": 31619,
                        "defaultValue": 2
                    },
                    {
                        "id": 128500,
                        "periodId": 31620,
                        "defaultValue": 3
                    }
                ],
                "targetPeriodDefaultValuesMap": {
                    "31619": {
                        "id": 128499,
                        "periodId": 31619,
                        "defaultValue": 2
                    },
                    "31620": {
                        "id": 128500,
                        "periodId": 31620,
                        "defaultValue": 3
                    }
                },
                "extendedFieldInfo": {
                    "programId": 973,
                    "alternateCurrencyIdentifier": "DocCoin"
                }
            }
        ],
        "leaderboardEnabled": false,
        "userCreated": false,
        "timeZoneName": "GMT"
    },
    "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

Field	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	Number	Identifier for the preferred POS till.
trackingType	Enum	The type of tracking the milestone is created for. Supported values: `DEFAULT`: Track a single target `UNIFIED` :Track multiple targets `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.
frequency	Number	Frequency count, based on the `frequencyType`.
recurringCycles	Number	Number of cycles for which the tracking recurs.
periods	Object	Details on target creation, updates, and time-frame.
-id	Integer	The unique ID of the target period.
-attribution	Object	Details on the creation and update details of the target period.
-- createdOn	String	Date the target period was created in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Note: This field will be deprecated in the future and is being replaced by `createdOnISO`.
-- createdOnISO	String	Indicates the start date and time of the target period in ISO 8601 format, returned in the server time zone. EU server example 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
--lastUpdatedOn	String	Date the target period was last updated in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Note: This field will be deprecated in the future and is being replaced by `lastUpdatedOnISO`.
--lastUpdatedOnISO	String	Indicates the last updated date and time of the target period in ISO 8601 format, returned in the server time zone. EU server example 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
--lastUpdatedBy	Object	Details on updates to the target period.
---id	Integer	Unique ID of the user who last modified the target period.
---code	String	Code of the user who last modified the target period.
---description	String	Description of the user who last modified the target period.
---name	String	Name of the user who last modified the target period.
---type	String	Type of user who last modified the target period.
-startDate	String	Start date of the target group, in `YYYY-MM-DD` format.
-endDate	String	End date of the target group, in `YYYY-MM-DD` format.
-refCode	Integer	Reference code of the target period.
-periodStatus	String	Current status of the target period. Supported values `NOT_STARTED`, `LIVE` and `ENDED`.
-targetGroupId	Integer	Unique ID of the target group.
-description	String	Description of the target group.
-active	Boolean	Current active status of the target period. If true, the target is currently active, else the target is inactive.
totalPeriods	Integer	Total number of periods for the target group.
description	String	Description of the target period.
targetEvaluationType	ENUM	Evaluation strategy for the target.
recurringCycles	Integer	Number of cycles for which the tracking recurs.
targetCycleStartDate	String	Start date of the target cycle in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Note: This field will be deprecated in the future and is being replaced by `targetCycleStartDateISO`.
targetCycleEndDate	String	End date of the target cycle in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Start date of the target cycle in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Note: This field will be deprecated in the future and is being replaced by `targetCycleEndDateISO`.
targetCycleStartDateISO	String	Indicates the start date and time of the target in ISO 8601 format, returned in the server time zone. EU server example 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
targetCycleEndDateISO	String	Indicates the end date and time of the target in ISO 8601 format, returned in the server time zone. EU server example 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
frequencyType	String	The frequency of each cycle in which the user has to achieve the target value.
trackingType	Enum	The type of tracking the milestone is created for.
targets	Object	Details on creation of the target.
-id	Boolean	Unique ID of the target.
-attribution	Object	Details on the creation and update details of the target.
-- createdOn	String	Date the target was created in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Note: This field will be deprecated in the future and is being replaced by `createdOnISO`.
-- createdOnISO	String	Indicates the creation date and time of the target in ISO 8601 format, returned in the server time zone. EU server example 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
-- lastUpdatedOn	String	Date the target was last updated in ISO 8601 `YYYY-MM-DDTHH:mm:ss.SSS` format. Note: This field will be deprecated in the future and is being replaced by `lastUpdatedOnISO`.
-- lastUpdatedOnISO	String	Indicates the last updated date and time of the target in ISO 8601 format, returned in the server time zone. EU server example 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
-- lastUpdatedBy	Object	Details on updates to the target.
--- id	Integer	Unique ID of the user who last modified the target.
--- code	Integer	Code of the user who last modified the target.
-- description	String	Description of the user who last modified the target.
--- name	String	Name of the user who last modified the target.
--- type	String	Type of user who last modified the target.
-- createdBy	Object	Details on creation of the target.
--- id	Integer	Unique ID of the user who created the target .
--- code	Integer	Code of the user who created the target.
--- description	String	Description of the user who created the target.
--- name	String	Name of the user who created the target.
--- type	String	Type of user who created the target.
---name	String	Unique name for the target.
--targetType	String	The type of target Supported values: `ALL`: Tracks points that a customer earns across a loyalty program and from a loyalty promotion. `REGULAR`: Track the points that a customer earns across a loyalty program. Points earned from promotions are excluded. `PROMOTION`: Tracks the points that a customer earns from a loyalty promotion.
--targetEntity	Enum	The KPI on which the target is tracked. For the transactional KPIs, the supported value for this are `TRANSACTION` and `LINEITEM`. For the Behavioural or EMF events, the supported value is `EVENT`. For the tracking based on rewards such as points, the supported value is `REWARDS`.
--eventName	String	Name of the event that triggers the target.
--targetGroupId	Integer	Unique ID of the target group associated with the target.
--description	String	Description of the target.
--active	Boolean	Current active status of the target. If true, the target is currently active, else the target is inactive.
-- expression	Boolean	Indicates if the target has an expression for evaluation.
-- expressionJson	String	A JSON expression that specifies the conditions required to achieve the target.
-- filters	Object	Details on the scope filters active on the target.
-- enrolmentMethod	Enum	The method of enrolment for the target. Supported values: `TRANSACTION`, `IMPORT`.
-- defaultValues	Object	Details on the default values for the target.
--- defaultValue	Float	A default value used in the target evaluation.
-- targetPeriodDefaultValuesMap	Object	Details on the default values for the target period.
-- extendedFieldInfo	Object	Details on extended field information for the target group.
-- programId	Integer	Unique ID of the loyalty program
-- alternateCurrencyIdentifier	String	Unique ID of the alternate currency.
leaderboardEnabled	Boolean	Indicates if the leaderboard feature is enabled.
userCreated	Boolean	Indicates if the target is a user-created target.
timezoneName	String	IANA time zone name for the target group; defaults to system time zone when omitted.
errors	null or Object	Contains error details if any occurred during the API request.
warnings	null or Object	Contains warning details if any occurred during the API request.

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