API Documentation

Create badges

post
https://{host}/api_gateway/v1/badges/badgeMeta
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

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

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/badges/badgeMeta' \
--data '{
    "name": "Badge Issue ",
    "description": "Make 5 transactions",
    "startOn":1764679795,
    "startOnISO": "2025-12-21T00:00:00Z",
    "expiresOn": 1796215795000,
    "expiresOnISO": "2026-09-20T03:46:40Z",
    "createdOnISO":"2026-12-21T03:46:40Z",

     "earnType": "ISSUE_EARN",
         "badgeRank": 3,
    "earnedBadgeExpiry": {
        "relativeExpirytype": "WEEKS",
        "value": 2,
        "expiryType": "RELATIVE"
    },
    "issuedBadgeExpiry": {
        "type": "FIXED_DATE",
        "expiresOn": 1926235957,
        "expiryType": "ABSOLUTE"
    },
    "isActive": true,
    "ownership": {
        "restrictedToOwners": [
            "Loyalty",
            "Audience_Campaigns",
            "Loyalty_Promotion",
            "Referral_Campaigns",
            "Rewards_Catalog",
            "Milestones",
            "Journeys",
            "Goodwill_Module",
            "Historical_Import"
        ]
    },
    "benefits": [
        {
            "benefitType": "COUPON",
            "seriesId": 13745
        }
    ],
  "images": [
    {
      "name": "Issued",
      "fileSvcHandle": "qwer-8634-8938",
        "url": "https://firebasestorage.googleapis.com/v0/b/createbadges.appspot.com/o/images%2Fsuccess1.jpg?alt=media&token=66b2f0bc-9c55-4e33-a5e9-c6be96d94f2d",
        "tag": "EARNED"
    }
  ],
"customerConstraints": [
    {
      "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
      "maxEarnLimit": 2,
      "durationType":"DAYS",
      "refreshRate":3,
      "startDayOfTheWeek":1
    }
],
    "badgeConstraints": [
        {
            "constraintType": "BADGE_FIXED_VALUE",
            "maxEarnLimit": 10000
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "DAYS",
            "rollValue": 1,
            "maxEarnLimit": 300
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "WEEKS",
            "rollValue": 1,
            "maxEarnLimit": 3000
        }
    ]
}'
curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/badges/badgeMeta' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWFkaH2YQ==' \
--header 'Cookie: _cfuvid=rvSJsUbK4DDG1qt9p.ywFArkr5WoVyHK8rR8vhrDpB4-1768813084882-0.0.1.1-604800000' \
--data '{
    "name": "badgetestjan16 01",
    
    "startOn": 1768714500,
    "expiresOn": 1769751300,
    "earnedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "FIXED_DATE",
        "expiresOn": 1769751300
    },
    "ownership": {
        "restrictedToOwners": [
            "Loyalty",
            "Milestones"
        ],
        "claims": [
            {
                "ownerType": "Loyalty",
                "referenceId": "626"
            }
        ]
    },
    "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": 10000
        },
        {
            "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
            "maxEarnLimit": 2,
            "durationType": "WEEKS",
            "refreshRate": 3,
            "startDayOfTheWeek": 1
        }
    
],
"earnType": "EARN"
}'

Request body parameters

FieldTypeRequiredDescription
idStringYesUnique badge meta ID generated during creation of the badge. Mandatory to pass the badge meta ID to update the badge.
nameStringYesName of the badge (e.g., "10% off on watches"). Badge name should be unique and is case sensitive.
descriptionStringOptionalBrief description of the badge (e.g., "Purchase 2 watches, get a $100 voucher").
startOnDate TimeConditionalTimestamp indicating when a badge starts in epoch seconds. 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.
Note: This field will be deprecated in the future and is being replaced by startOnISO
startOnISOStringOptional

Defines the badge's start date in ISO 8601 format, including 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.

Notes:
  • This parameter overrides the value set in the startOn parameter.
  • The date cannot be set more than 100 years in the past.
expiresOnDate TimeConditionalTimestamp indicating when the badge ends in epoch seconds. expiresOn or expiresOnISO is required when expiry type is FIXED_DATE.
Note: This field will be deprecated in the future and is being replaced by expiresOnISO
expiresOnISOStringConditional

Defines the badge's expiration date in ISO 8601 format, including the region offset.
For example:
The expiration date is at 14:30:45 on December 16, 2025, in India.
Format for the request parameter: 2025-12-16T14:30:45+05:30.

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).
earnTypeEnumEnumThe 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).
badgeRankIntegerOptionalBadge 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.
.earnedBadgeExpiryObjectYesObject containing details about the expiry of earned badges.
..relativeExpiryTypeEnumOptionalExpiry type relative to the badge issue. Supported values: "DAYS", "WEEKS", "MONTHS". Applicable when expiryType is RELATIVE.
..expiryTypeEnumYesType 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.
..typeEnumYesType 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.
..expireWithBadgeMetaBooleanYesIndicates if the badge should expire based on the mandatory parameter expiresOn.
ownershipObjectYesAn object containing ownership restrictions. Cannot remove an owner if it has an active badge claim associated with it.
ownership.restrictedToOwnersObjectYesList 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
.customerConstraintsArrayOptionalList of constraints specific to customers. Applicable when earnType is EARN.
..constraintTypeEnumOptionalType of customer constraint. Supported values: "CUSTOMER_BADGE_FIXED_WINDOW", "CUSTOMER_BADGE_FIXED_VALUE", "CUSTOMER_BADGE_ROLLING_WINDOW", "CUSTOMER_BADGE_NO_LIMIT".
..durationTypeEnumOptionalDuration of the badge constraint. Supported values: "DAILY", "WEEKLY", "MONTHLY". If DAILY, refreshRate is mandatory. If WEEKLY, startDayOfTheWeek is mandatory (default: Monday).
..refreshRateIntegerOptionalNumber of days the fixed window duration is.
..startDayOfTheWeekEnumOptionalDay on which the cycle starts. Supported values: "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY".
..maxEarnLimitIntegerOptionalThe maximum limit a customer can earn during the week.
..maxEarnForDaysIntegerOptionalMaximum earning limit per day. Applicable for CUSTOMER_BADGE_ROLLING_WINDOW.
..rollForDaysIntegerOptionalThe number of days for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
..maxEarnForWeeksIntegerOptionalMaximum earning limit per week. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
.rollForWeeksIntegerOptionalNumber of weeks for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
..maxEarnForMonthsIntegerOptionalMaximum earning limit per month. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
..rollForMonthsIntegerOptionalNumber of months for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
.badgeConstraintsArrayOptionalRestrictions that are applied on the badge. Applicable when issue type is EARN.
..constraintTypeEnumOptionalType of badge constraint. Supported values: "BADGE_FIXED_WINDOW", "BADGE_ROLLING_WINDOW", "BADGE_FIXED_VALUE", "BADGE_NO_LIMIT".
..durationTypeEnumOptionalDuration of the badge constraint. Supported values: "DAILY", "WEEKLY", "MONTHLY". If DAILY, refreshRate is mandatory. If WEEKLY, startDayOfTheWeek is mandatory (default: Monday).
..refreshRateIntegerOptionalNumber of days the fixed window duration is.
..startDayOfTheWeekEnumOptionalDay on which the cycle starts. Supported values: "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY".
..maxEarnLimitIntegerOptionalThe maximum limit a customer can earn during the period.
..rollTypeEnumOptionalTimeframe of the rolling window. Supported values: "DAYS", "WEEKS", "MONTHS".
..rollValueIntegerOptionalValue for rolling window calculation.
..maxEarnLimitIntegerOptionalMaximum limit a badge can earn.
isActiveBooleanYesIndicates whether the badge is currently active.
customFieldsObjectOptionalList of custom fields.
customFields.customFieldNameStringOptionalName of the custom field.
customFields.customFieldValueStringOptionalValue of the custom field.
badgeGroupIdStringOptionalUnique group ID associated with the badge. To add the badge to a group, pass badgeGroupId value.

📘

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

Example response

{
    "data": {
        "id": "696df3810772ad476ecf6a07",
        "badgeNumericId": 107,
        "orgId": 100737,
        "name": "Badge Issue earn type",
        "description": "Make 5 transactions",
        "startOn": 1716803487,
        "startOnISO": "2024-05-27T09:51:27Z",
        "expiresOn": 1726804000,
        "expiresOnISO": "2024-09-20T03:46:40Z",
        "earnedBadgeExpiry": {
            "expiryType": "RELATIVE",
            "relativeExpirytype": "WEEKS",
            "value": 2
        },
        "issuedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1926235957,
            "expiresOnISO": "2031-01-15T09:32:37Z",
            "expireWithBadgeMeta": false
        },
        "images": [
            {
                "name": "Issued",
                "fileSvcHandle": "qwer-8634-8938",
                "url": "https://firebasestorage.googleapis.com/v0/b/createbadges.appspot.com/o/images%2Fsuccess1.jpg?alt=media&token=66b2f0bc-9c55-4e33-a5e9-c6be96d94f2d",
                "tag": "EARNED"
            }
        ],
        "ownership": {
            "restrictedToOwners": [
                "Loyalty",
                "Audience_Campaigns"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "e6791ec9-e92f-34af-bdc3-be2607fdf82c",
                "durationType": "DAYS",
                "refreshRate": 3,
                "maxEarnLimit": 2,
                "cycleStatus": "ACTIVE",
                "startDate": 1716803487,
                "startDateISO": "2024-05-27T09:51:27Z",
                "endDate": 1926235957,
                "endDateISO": "2031-01-15T09:32:37Z"
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_VALUE",
                "maxEarnLimit": 10000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "WEEKS",
                "rollValue": 1,
                "maxEarnLimit": 3000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "DAYS",
                "rollValue": 1,
                "maxEarnLimit": 300
            }
        ],
        "benefits": [],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": 3,
        "earnType": "ISSUE_EARN",
        "status": "EXPIRED",
        "createdOn": 1768813441.180822,
        "createdOnISO": "2026-01-19T09:04:01Z",
        "createdBy": 75197372,
        "lastUpdatedOn": 1768813441.180822,
        "lastUpdatedOnISO": "2026-01-19T09:04:01Z",
        "lastUpdatedBy": 75197372,
        "customFields": {},
        "active": true
    },
    "errors": [],
    "warnings": []
}
{
    "data": {
        "id": "696df21c0772ad476ecf69d4",
        "badgeNumericId": 106,
        "orgId": 100737,
        "name": "badgetestjan16 01",
        "description": null,
        "startOn": 1768714500,
        "startOnISO": "2026-01-18T05:35:00Z",
        "expiresOn": 1769751300,
        "expiresOnISO": "2026-01-30T05:35:00Z",
        "earnedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1769751300,
            "expiresOnISO": "2026-01-30T05:35:00Z",
            "expireWithBadgeMeta": false
        },
        "issuedBadgeExpiry": null,
        "images": [],
        "ownership": {
            "restrictedToOwners": [
                "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
            },
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "53b1267d-4907-364a-a2ae-5989a9b2123a",
                "durationType": "WEEKS",
                "startDayOfTheWeek": "TUESDAY",
                "maxEarnLimit": 2,
                "startDateISO": null,
                "endDateISO": null
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_VALUE",
                "maxEarnLimit": 10000
            }
        ],
        "benefits": [],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": null,
        "earnType": "EARN",
        "status": "LIVE",
        "createdOn": 1768813084.80786,
        "createdOnISO": "2026-01-19T08:58:04Z",
        "createdBy": 75197372,
        "lastUpdatedOn": 1768813084.80786,
        "lastUpdatedOnISO": "2026-01-19T08:58:04Z",
        "lastUpdatedBy": 75197372,
        "customFields": {},
        "active": true
    },
    "errors": [],
    "warnings": []
}

Response parameters

ParameterDescription
.dataThe main container for the response data.
..idUnique identifier for the badge.
..orgIdIdentifier for the organization associated with the badge.
..nameName of the badge.
..descriptionDescription of the badge.
..startOnTimestamp for when the badge starts.
.earnedBadgeExpiryDetails about the expiry of an earned badge.
..expiryTypeType of expiry for the earned badge.
..typeType of badge expiry.
..expiresOnTimestamp indicating when the badge ends, in epoch milliseconds time format.
..expiresOnISOTimestamp indicating when the badge ends, in ISO 8601 time format.
.issuedBadgeExpiryDetails about the expiry of the issued badge
.imagesArray of images related to the item.
..nameName of the image.
..fileSvcHandleService handle for the image file.
..urlURL of the image.
.ownershipDetails about the ownership of the item.
.ownership.restrictedToOwnersArray of owner types who have restricted access.
.customerConstraintsLimit on how many badges can be issued to a particular customer.
.badgeConstraintsLimit on how many quantities of a reward can be given to customers.
.badgeGroupIdGroup ID for the badge.
.badgeRankBadge rank is the rank within a group. A user can define the badge rank even if a group is not linked with the badge.
.earnTypeThe 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.
.issuedCountCount of how many times the badge has been issued.
.earnedCountCount of how many times the badge has been earned.
.statusThe 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.
.createdOnTimestamp for when the badge was created.
.createdOnISO

Timestamp for when the badge was created, 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.

.createdByIdentifier of the user who created the badge.
.lastUpdatedOnTimestamp for the last update made to the badge, in epoch milliseconds timestamp format.
lastUpdatedOnISO

Timestamp for the last update made to the badge, 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.

.lastUpdatedByIdentifier of the user who last updated the badge.
.customFieldsList of custom fields.
.customFields.customFieldNameName of the custom field.
.customFields.customFieldValueValue of the custom field.
.activeIndicates whether the badge is active or not.
errorsContains details of any error.
warningsContains details of any warning.
{
    "data": {
        "id": "692d2b942814b4096ebb9aa1",
        "badgeNumericId": 81,
        "orgId": 100737,
        "name": "Badge Issue earn2d72",
        "description": "Make 5 transactions",
        "startOn": 1753056000,
        "startOnISO": "2025-07-21T00:00:00Z",
        "expiresOn": 1789876000,
        "expiresOnISO": "2026-09-20T03:46:40Z",
        "earnedBadgeExpiry": {
            "expiryType": "RELATIVE",
            "relativeExpirytype": "WEEKS",
            "value": 2
        },
        "issuedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1926235957,
            "expiresOnISO": "2031-01-15T09:32:37Z",
            "expireWithBadgeMeta": false
        },
        "images": [
            {
                "name": "Issued",
                "fileSvcHandle": "qwer-8634-8938",
                "url": "https://firebasestorage.googleapis.com/v0/b/createbadges.appspot.com/o/images%2Fsuccess1.jpg?alt=media&token=66b2f0bc-9c55-4e33-a5e9-c6be96d94f2d",
                "tag": "EARNED"
            }
        ],
        "ownership": {
            "restrictedToOwners": [
                "Referral_Campaigns",
                "Audience_Campaigns",
                "Loyalty_Promotion",
                "Goodwill_Module",
                "Journeys",
                "Loyalty",
                "Milestones",
                "Historical_Import",
                "Rewards_Catalog"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "e6791ec9-e92f-34af-bdc3-be2607fdf82c",
                "durationType": "DAYS",
                "refreshRate": 3,
                "maxEarnLimit": 2,
                "cycleStatus": "ACTIVE",
                "startDate": 1753056000,
                "startDateISO": "2025-07-21T00:00:00Z",
                "endDate": 1926235957,
                "endDateISO": "2031-01-15T09:32:37Z"
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "DAYS",
                "rollValue": 1,
                "maxEarnLimit": 300
            },
            {
                "constraintType": "BADGE_FIXED_VALUE",
                "maxEarnLimit": 10000
            },
            {
                "constraintType": "BADGE_ROLLING_WINDOW",
                "rollType": "WEEKS",
                "rollValue": 1,
                "maxEarnLimit": 3000
            }
        ],
        "benefits": [
            {
                "benefitType": "COUPON",
                "seriesId": 13745
            }
        ],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": 3,
        "earnType": "ISSUE_EARN",
        "status": "LIVE",
        "createdOn": 1764567956.97866,
        "createdOnISO": "2025-12-01T05:45:56Z",
        "createdBy": 75197941,
        "lastUpdatedOn": 1764567956.97866,
        "lastUpdatedOnISO": "2025-12-01T05:45:56Z",
        "lastUpdatedBy": 75197941,
        "customFields": {},
        "active": true
    },
    "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.
705Expiry date is mandatory.
Body Params
json
Headers
string
Defaults to migration
Responses

Updated 2 months ago

Language
Credentials
Basic
base64
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 2 months ago