API Documentation
Start typing to search…

Update badges

put
https://{host}/api_gateway/v1/badges/badgeMeta

This API allows you to update badges.

👍

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

❗️

Attention

You cannot claim a badge during badge creation or updation.

Badge name should be unique and is case sensitive.

Prerequisites

  • Authentication: Basic or OAuth authentication
  • Default access group

Resource information

URI/api_gateway/v1/badges/badgeMeta
HTTP methodPUT
PaginationNA
Batch supportNA

API endpoint example

https://eucrm.cc.capillarytech.com/api_gateway/v1/badges/badgeMeta

Request body parameters

Field

Type

Required

Description

id

String

Yes

Unique badge meta ID generated during creation of the badge. Mandatory to pass the badge meta ID to update the badge.

name

String

Yes

Name of the badge (e.g., "10% off on watches"). Badge name should be unique and is case sensitive.

description

String

Optional

Brief description of the badge (e.g., "Purchase 2 watches get a $100 voucher").

startOn

Date Time

Conditional

Timestamp indicating when a badge starts in epoch milliseconds. Cannot be set more than 100 years in the past. Cannot be changed for live or expired badges. Upcoming badges allow updating the startOn date, even to a past date.

startOnISO

String

Optional

Defines the badge's start date in ISO 8601 format in UTC and is independent of the user’s local time zone.

For example:
The start date is at 14:30:45 on December 16, 2025.Format for the request parameter: 2025-12-16T14:30:45Z

Notes:

  • This parameter overrides the value set in the startOn parameter.
  • The date cannot be set more than 100 years in the past.

expiresOn

Date Time

Conditional

Timestamp indicating when the badge ends in epoch milliseconds. expiresOn or expiresOnISO is required when expiry type is FIXED_DATE.

expiresOnISO

String

Conditional

Defines the badge's expiry date in ISO 8601 format in UTC and is independent of the user’s local time zone.

For example: The expiry date is at 14:30:45 on December 16, 2025.Format for the request parameter: 2025-12-16T14:30:45Z

Notes:

  • This parameter overrides the value set in the expiresOn parameter.
  • If expiresOnISO is provided, the system ignores expiresOn. expiresOn is only used if expiresOnISO is null.
  • This parameter is mandatory when the expiry type is set to FIXED_DATE (either expiresOn or expiresOnISO must be provided).

.earnedBadgeExpiry

Object

Yes

Object containing details about the expiry of earned badges.

...expiryType

Enum

Yes

Type of badge expiry. Supported values: "RELATIVE", "ABSOLUTE", "NEVER". RELATIVE: Based on when the badge was issued.
ABSOLUTE: Based on the fixed date from the badge issual.
NEVER: The badges will never expire after issual.

..type

Enum

Yes

Type refers to the badge expiration method. Supported values: "WITH_BADGE_META", "FIXED_DATE". WITH_BADGE_META: The expiry is based on the mandatory expiresOn parameter. FIXED_DATE: The expiry is based on the expiry date of the incentives associated with the badge.

..expireWithBadgeMeta

Boolean

Yes

Indicates if the badge should expire based on the mandatory parameter expiresOn.

..relativeExpiryType

Enum

Optional

Expiry type relative to the badge issue. Supported values: "DAYS", "WEEKS", "MONTHS". Applicable when expiryType is RELATIVE.

ownership

Object

Yes

An object containing ownership restrictions. Cannot remove an owner if it has an active badge claim associated with it.

ownership.restrictedToOwners

Object

Yes

List of owner categories that are allowed to claim the badge. Supported values: Loyalty, Loyalty_Promotion, Referral_Campaigns, Journeys, Audience_Campaigns, Membercare, Rewards_Catalog, Goodwill_Module, Milestones, Historical_Import

.customerConstraints

Array

Optional

List of constraints specific to customers. Applicable when earnType is EARN.

..constraintType

Enum

Optional

Type of customer constraint. Supported values: "CUSTOMER_BADGE_FIXED_WINDOW", "CUSTOMER_BADGE_FIXED_VALUE", "CUSTOMER_BADGE_ROLLING_WINDOW", "CUSTOMER_BADGE_NO_LIMIT".

..durationType

Enum

Optional

Duration of the badge constraint. Supported values: "DAILY", "WEEKLY", "MONTHLY". If DAILY, refreshRate is mandatory. If WEEKLY, startDayOfTheWeek is mandatory (default: Monday).

..refreshRate

Integer

Optional

Number of days the fixed window duration is.

..startDayOfTheWeek

Enum

Optional

Day on which the cycle starts. Supported values: "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY".

..maxEarnLimit

Integer

Optional

The maximum limit a customer can earn during the week.

..maxEarnForDays

Integer

Optional

Maximum earning limit per day. Applicable for CUSTOMER_BADGE_ROLLING_WINDOW.

..rollForDays

Integer

Optional

The number of days for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.

..maxEarnForWeeks

Integer

Optional

Maximum earning limit per week. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.

.rollForWeeks

Integer

Optional

Number of weeks for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.

..maxEarnForMonths

Integer

Optional

Maximum earning limit per month. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.

..rollForMonths

Integer

Optional

Number of months for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.

.badgeConstraints

Array

Optional

Restrictions that are applied on the badge. Applicable when issue type is EARN.

..constraintType

Enum

Optional

Type of badge constraint. Supported values: "BADGE_FIXED_WINDOW", "BADGE_ROLLING_WINDOW", "BADGE_FIXED_VALUE", "BADGE_NO_LIMIT".

..durationType

Enum

Optional

Duration of the badge constraint. Supported values: "DAILY", "WEEKLY", "MONTHLY". If DAILY, refreshRate is mandatory. If WEEKLY, startDayOfTheWeek is mandatory (default: Monday).

..refreshRate

Integer

Optional

Number of days the fixed window duration is.

..startDayOfTheWeek

Enum

Optional

Day on which the cycle starts. Supported values: "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY".

..maxEarnLimit

Integer

Optional

The maximum limit a customer can earn during the period.

..rollType

Enum

Optional

Timeframe of the rolling window. Supported values: "DAYS", "WEEKS", "MONTHS".

..rollValue

Integer

Optional

Value for rolling window calculation.

..maxEarnLimit

Integer

Optional

Maximum limit a badge can earn.

earnType

Enum

Yes

The method the brand can issue the badge. Supported values: "EARN", "ISSUE_EARN". EARN: Selected customers are enrolled for the badge and upon fulfillment of the earn condition, the badge is issued. ISSUE_EARN: The badges are issued directly to the customer who fulfills the earn condition (no enrolment to badges-related program).

active

Boolean

Yes

Indicates whether the badge is currently active.

customFields

Object

Optional

List of custom fields.

customFields.customFieldName

String

Optional

Name of the custom field.

customFields.customFieldValue

String

Optional

Value of the custom field.

badgeGroupId

String

Optional

Unique group ID associated with the badge. To add the badge to a group, pass badgeGroupId value.

badgeRank

Integer

Optional

Badge rank is the rank of a badge within a group, the user can define the badge rank even if the group is not linked with the badge.


📘

Note

  • Fields marked with * in the original documentation are required
  • Timestamps should be in epoch time format
  • The system uses the server's cluster time for determining badge expiry
  • Badge names are case sensitive and must be unique
  • You cannot remove an owner if it has an active badge claim associated with it****
 {
        "id": "8",
        "orgId": 100606,
        "name": "EARN-TYPE",
        "description": "Purchase 5 pet products in 3 months and get a pet grooming voucher",
        "startOn": 1799632870.000000000,
        "expiresOn": 1828754110.000000000,
        "earnedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "WITH_BADGE_META",
            "expiresOn": null,
            "expireWithBadgeMeta": true
        },
        "issuedBadgeExpiry": null,
        "images": [],
        "ownership": {
            "restrictedToOwners": [
                "Audience_Campaigns",
                "Loyalty",
                "Milestones"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_VALUE",
                "maxEarnLimit": 100
            },
            {
                "constraintType": "CUSTOMER_BADGE_ROLLING_WINDOW",
                "maxEarnForDays": 1,
                "rollForDays": 1,
                "maxEarnForWeeks": 2,
                "rollForWeeks": 1,
                "maxEarnForMonths": 10,
                "rollForMonths": 1
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_VALUE",
                "maxEarnLimit": 1000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "DAYS",
                "rollValue": 1,
                "maxEarnLimit": 100
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "MONTHS",
                "rollValue": 1,
                "maxEarnLimit": 10000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "WEEKS",
                "rollValue": 1,
                "maxEarnLimit": 2000
            }
        ],
        "badgeGroupId": null,
        "badgeRank": 1,
        "earnType": "EARN",
        "issuedCount": 0,
        "earnedCount": 0,
        "status": "UPCOMING",
        "createdOn": 1707897126.091000000,
        "createdBy": 75097962,
        "lastUpdatedOn": 1707897126.091000000,
        "lastUpdatedBy": 75097962,
        "active": false
    }
{
    "id": "661e11563753c37878a8b2c7",
    "orgId": 100606,
    "name": "This is a badge",
    "description": "Purchase products worth minimum 1K in the month of March and get this badge",
    "startOn": 1808338345.000000000,
    "expiresOn": 1828754110.000000000,
    "earnedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "FIXED_DATE",
        "expiresOn": 1828754110.000000000,
        "expireWithBadgeMeta": false
    },
    "issuedBadgeExpiry": null,
    "images": [],
    "ownership": {
        "restrictedToOwners": [
            "Loyalty"
        ],
        "claims": []
    },
   "customerConstraints": [
        {
            "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
            "referenceId": "e6791ec9-e92f-34af-bdc3-be2607fdf82c",
            "durationType": "DAYS",
            "refreshRate": 5,
            "maxEarnLimit": 1,
            "cycleStatus": "UPCOMING",
            "startDate": 1808338345.000000000,
            "endDate": 1828754110.000000000
        }
    ],
   /*  "customerConstraints": [
       
        {
            "constraintType": "CUSTOMER_BADGE_ROLLING_WINDOW",
            "maxEarnForDays": 50,
            "rollForDays": 5,
            "maxEarnForWeeks": 100,
            "rollForWeeks": 1,
            "maxEarnForMonths": 200,
            "rollForMonths": 1
        },
        {
            "constraintType": "CUSTOMER_BADGE_FIXED_VALUE",
            "maxEarnLimit": 5000
        }
    ],*/
    "badgeConstraints": [
        {
            "constraintType": "BADGE_FIXED_VALUE",
            "maxEarnLimit": 1000
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "DAYS",
            "rollValue": 1,
            "maxEarnLimit": 100
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "WEEKS",
            "rollValue": 1,
            "maxEarnLimit": 2000
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "MONTHS",
            "rollValue": 1,
            "maxEarnLimit": 10000
        }
    ],
    "badgeGroupId": null,
    "badgeRank": null,
    "earnType": "EARN",
    "status": "UPCOMING",
    "createdOn": 1713246550.885000000,
    "createdBy": 75097962,
    "lastUpdatedOn": 1713246550.885000000,
    "lastUpdatedBy": 75097962,
    "customFields": {
    
    },
    "active": true
}
{
    "id" : "66decf4459a5c872324b9577",
    "name": "Badge Issue earn40",
	"description": "Badge With coupon benefit updated 2",
    "issuedBadgeExpiry": {
       "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1726655584
    },
    "earnedBadgeExpiry": {
       "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1726655584
    },
    "ownership": {
		"restrictedToOwners": [
			"Loyalty"
		],
		"claims": [{
				"ownerType": "Loyalty",
				"referenceId": "xyz"
			}
		]
	},
    "startOn": 1725964384,
    "expiresOn": 1726655584,  // Cannot be updated to past date.
    "earnType": "EARN"
}

Response parameters

Parameter

Description

.data

The main container for the response data.

..id

Unique identifier for the badge.

..orgId

Identifier for the organization associated with the badge.

..name

Name of the badge.

..description

Description of the badge.

..startOn

Timestamp for when the badge starts.

.earnedBadgeExpiry

Details about the expiry of an earned badge.

..expiryType

Type of expiry for the earned badge.

..type

Type of badge expiry.

..expiresOn

Timestamp indicating when the badge ends, in epoch milliseconds time format.

..expiresOnISO

Timestamp indicating when the badge ends, in ISO 8601 time format.

.issuedBadgeExpiry

Details about the expiry of the issued badge

.images

Array of images related to the item.

..name

Name of the image.

..fileSvcHandle

Service handle for the image file.

..url

URL of the image.

.ownership

Details about the ownership of the item.

.ownership.restrictedToOwners

Array of owner types who have restricted access.

.customerConstraints

Limit on how many badges can be issued to a particular customer.

.badgeConstraints

Limit on how many quantities of a reward can be given to customers.

.badgeGroupId

Group ID for the badge.

.badgeRank

Badge rank is the rank within a group. A user can define the badge rank even if a group is not linked with the badge.

.earnType

The method by which the brand can issue the badge. Supported values: EARN, ISSUE EARN. - Earn: The selected customers are enrolled for the badge, and upon fulfillment of the earn condition, the badge is issued. - Issue Earn: Badges are issued directly to the customer who fulfills the earn condition.

.issuedCount

Count of how many times the badge has been issued.

.earnedCount

Count of how many times the badge has been earned.

.status

The badge can have three statuses upon creation. Supported values: LIVE, UPCOMING, ENDED/EXPIRED. - LIVE: Badges that are in a live state and can be earned. - UPCOMING: Badges that are upcoming on a future date. - EXPIRED/ENDED: Badges that have expired and cannot be earned.

.createdOn

Timestamp for when the badge was created.

.createdOnISO

Timestamp for when the badge was created, in UTC. Time format: ISO 8601 timestamp

.createdBy

Identifier of the user who created the badge.

.lastUpdatedOn

Timestamp for the last update made to the badge, in epoch milliseconds timestamp format.

lastUpdatedOnISO

Timestamp for the last update made to the badge, in UTC. Time format: ISO 8601 timestamp

.lastUpdatedBy

Identifier of the user who last updated the badge.

lastUpdatedByISO

Identifier of the user who last updated the badge.

.customFields

List of custom fields.

.customFields.customFieldName

Name of the custom field.

.customFields.customFieldValue

Value of the custom field.

.active

Indicates whether the badge is active or not.

errors

Contains details of any error.

warnings

Contains details of any warning.

{
    "data": {
        "id": "8",
        "orgId": 100606,
        "name": "EARN-TYPE",
        "description": "Purchase 5 pet products in 3 months and get a pet grooming voucher",
        "startOn": 1799632870.000000000,
        "expiresOn": 1828754110.000000000,
        "earnedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "WITH_BADGE_META",
            "expiresOn": null,
            "expireWithBadgeMeta": true
        },
        "issuedBadgeExpiry": null,
        "images": [],
        "ownership": {
            "restrictedToOwners": [
                "Audience_Campaigns",
                "Milestones",
                "Loyalty"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_VALUE",
                "maxEarnLimit": 100
            },
            {
                "constraintType": "CUSTOMER_BADGE_ROLLING_WINDOW",
                "maxEarnForDays": 1,
                "rollForDays": 1,
                "maxEarnForWeeks": 2,
                "rollForWeeks": 1,
                "maxEarnForMonths": 10,
                "rollForMonths": 1
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_VALUE",
                "maxEarnLimit": 1000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "WEEKS",
                "rollValue": 1,
                "maxEarnLimit": 2000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "MONTHS",
                "rollValue": 1,
                "maxEarnLimit": 10000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "DAYS",
                "rollValue": 1,
                "maxEarnLimit": 100
            }
        ],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": 1,
        "earnType": "EARN",
        "status": "UPCOMING",
        "createdOn": 1707897126.091000000,
        "createdBy": 75097962,
        "lastUpdatedOn": 1713852683.788076000,
        "lastUpdatedBy": 75097962,
        "customFields": {},
        "active": false
    },
    "errors": [],
    "warnings": []
}
{
    "data": {
        "id": "661e11563753c37878a8b2c7",
        "orgId": 100606,
        "name": "This is a badge",
        "description": "Purchase products worth minimum 1K in the month of March and get this badge",
        "startOn": 1808338345.000000000,
        "expiresOn": 1828754110.000000000,
        "earnedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1828754110.000000000,
            "expireWithBadgeMeta": false
        },
        "issuedBadgeExpiry": null,
        "images": [],
        "ownership": {
            "restrictedToOwners": [
                "Loyalty"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "1c11e757-4f00-3bb2-8aa0-b34e25083bb3",
                "durationType": "DAYS",
                "refreshRate": 5,
                "maxEarnLimit": 1,
                "cycleStatus": "UPCOMING",
                "startDate": 1808338345.000000000,
                "endDate": 1828754110.000000000
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_VALUE",
                "maxEarnLimit": 1000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "WEEKS",
                "rollValue": 1,
                "maxEarnLimit": 2000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "DAYS",
                "rollValue": 1,
                "maxEarnLimit": 100
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "MONTHS",
                "rollValue": 1,
                "maxEarnLimit": 10000
            }
        ],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": null,
        "earnType": "EARN",
        "status": "UPCOMING",
        "createdOn": 1713246550.885000000,
        "createdBy": 75097962,
        "lastUpdatedOn": 1713955758.488460000,
        "lastUpdatedBy": 75097962,
        "customFields": {},
        "active": true
    },
    "errors": [],
    "warnings": []
}
{
    "data": {
        "id": "66decf4459a5c872324b9577",
        "badgeNumericId": 47,
        "orgId": 100458,
        "name": "Badge Issue earn40",
        "description": "Badge With coupon benefit updated 2",
        "startOn": 1725964384.000000000,
        "expiresOn": 1726655584.000000000,
        "earnedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1726655584.000000000,
            "expireWithBadgeMeta": false
        },
        "issuedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1726655584.000000000,
            "expireWithBadgeMeta": false
        },
        "images": [],
        "ownership": {
            "restrictedToOwners": [
                "Loyalty"
            ],
            "claims": []
        },
        "customerConstraints": [],
        "badgeConstraints": [],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": null,
        "earnType": "EARN",
        "status": "UPCOMING",
        "createdOn": 1725878084.045000000,
        "createdBy": 75130850,
        "lastUpdatedOn": 1725878207.750104000,
        "lastUpdatedBy": 75130850,
        "customFields": {},
        "active": true
    },
    "errors": [],
    "warnings": []
}
    "errors": [
        {
            "code": 723,
            "message": "Start Date cannot change once the badge is live",
            "reference": null
        },
    "errors": [
        {
            "code": 720,
            "message": "Start Date should be before End Date",
            "reference": null
        }
    "errors": [
        {
            "code": 724,
            "message": "Expiry Date cannot be past date",
            "reference": null
        }
    "errors": [
        {
            "code": 826,
            "message": "Change from rolling window or fixed constraint to fixed window or vice versa is not allowed.",
            "reference": null
        }

API-specific error codes

Error codeDescription
400Invalid enum value
720Start Date should be before End Date
723Start Date cannot change once the badge is live
724Expiry Date cannot be past date
826Change from rolling window or fixed constraint to fixed window or vice versa is not allowed.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!