API Documentation
Start typing to search…

Create target group based on alternate currencies

post
https://{host}/v3/targetGroups

Create a target group/milestone based on alternate currencies.

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

ParameterValue
URIv3/targetGroups
HTTP MethodPOST
PaginationNo
Rate LimitNo
Batch SupportNo

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.

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": 2779,
        "name": "uatTargetGroup96",
        "fromDate": "2025-10-07",
        "toDate": "2025-11-25",
        "active": true,
        "preferredTillId": 75155297,
        "periods": [
            {
                "id": 30186,
                "attribution": {
                    "createdOn": "2025-11-25T11:57:23.000+0000",
                    "createdOnISO": "2025-11-25T11:57:23Z",
                    "lastUpdatedOn": "2025-11-25T11:57:23.000+0000",
                    "lastUpdatedOnISO": "2025-11-25T11:57:23Z",
                    "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": 2779,
                "description": "p1",
                "active": true
            },
            {
                "id": 30187,
                "attribution": {
                    "createdOn": "2025-11-25T11:57:23.000+0000",
                    "createdOnISO": "2025-11-25T11:57:23Z",
                    "lastUpdatedOn": "2025-11-25T11:57:23.000+0000",
                    "lastUpdatedOnISO": "2025-11-25T11:57:23Z",
                    "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": 2779,
                "description": "p2",
                "active": true
            }
        ],
        "totalPeriods": 2,
        "targetEvaluationType": "FIXED_CALENDAR_WINDOW",
        "recurringCycles": 2,
        "frequency": 2,
        "targetCycleStartDate": "2025-07-21T00:00:00.000Z",
        "targetCycleEndDate": "2025-07-23T23:59:59.000Z",
        "targetCycleStartDateISO": "2025-07-21T00:00:00Z",
        "targetCycleEndDateISO": "2025-07-23T23:59:59Z",
        "trackingType": "DEFAULT",
        "targets": [
            {
                "id": 3026,
                "attribution": {
                    "createdOn": "2025-11-25T11:57:23.217+0000",
                    "createdOnISO": "2025-11-25T11:57:23Z",
                    "lastUpdatedOn": "2025-11-25T11:57:23.217+0000",
                    "lastUpdatedOnISO": "2025-11-25T11:57:23Z",
                    "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_96",
                "targetType": "ALL",
                "targetEntity": "ALTERNATE_CURRENCIES",
                "eventName": "TransactionAdd",
                "targetGroupId": 2779,
                "active": true,
                "expression": "true",
                "expressionJson": "{\"arity\":\"literal\",\"value\":\"true\",\"type\":\"boolean:primitive\"}",
                "filters": [],
                "enrolmentMethod": "IMPORT",
                "defaultValues": [
                    {
                        "id": 127093,
                        "periodId": 30186,
                        "defaultValue": 2
                    },
                    {
                        "id": 127094,
                        "periodId": 30187,
                        "defaultValue": 3
                    }
                ],
                "targetPeriodDefaultValuesMap": {
                    "30186": {
                        "id": 127093,
                        "periodId": 30186,
                        "defaultValue": 2
                    },
                    "30187": {
                        "id": 127094,
                        "periodId": 30187,
                        "defaultValue": 3
                    }
                },
                "extendedFieldInfo": {
                    "programId": 783,
                    "alternateCurrencyIdentifier": "DocCoin"
                }
            }
        ],
        "leaderboardEnabled": false,
        "userCreated": false,
        "timeZoneName": "Asia/Kolkata"
    },
    "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.

-- createdOnISO

String

Date the target period was created in ISO 8601 YYYY-MM-DDTHH:mm:ssZ format with the timezone included.

--lastUpdatedOn

String

Date the target period was last updated in ISO 8601 YYYY-MM-DDTHH:mm:ss.SSS format.

--lastUpdatedOnISO

String

Date the target period was last updated in ISO 8601 YYYY-MM-DDTHH:mm:ssZ format with the timezone included.

--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.

targetCycleEndDate

String

End date of the target cycle in ISO 8601 YYYY-MM-DDTHH:mm:ss.SSS format.

targetCycleStartDateISO

String

Start date of the target cycle in ISO 8601 YYYY-MM-DDTHH:mm:ssZ format with the timezone included.

targetCycleEndDate

String

End date of the target cycle in ISO 8601 YYYY-MM-DDTHH:mm:ssZ format with the timezone included.

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.

-- createdOnISO

String

Date the target was created in ISO 8601 YYYY-MM-DDTHH:mm:ssZ format with the timezone included.

-- lastUpdatedOn

String

Date the target was last updated in ISO 8601 YYYY-MM-DDTHH:mm:ss.SSS format.

-- lastUpdatedOnISO

String

Date the target was last updated in ISO 8601 YYYY-MM-DDTHH:mm:ssZ format with the timezone included.

-- 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

CodeDescription
310069Target group name already exists
300004Invalid input, check all values and ensure they are correct.
310008Length of Target rule name cannot exceed 200
310033Invalid target entity and target type combination
310146Invalid program id
310094Target rule metadata is required in case of EXTENDED_FIELD/ALTERNATE_CURRENCIES target type
310147Invalid or null Alternate Currency Identifier for target rule
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!