Create badges

This API allows you to create new 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 methodPOST
PaginationNA
Rate limitNA
Batch supportNA

API endpoint example

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

Header

HeaderValueDescription
X-CAP-BADGES-MIGRATIONmigrationIt enables you to use historical badges. If you are enabling this header, you can use a historical badge and it allows you to define a past date in the StartOn field.
Notes:

- - RequestId can be either passed in API headers or will be auto-generated for not added for all imported records in a single batch.

Request body parameters

Field NameData TypeDescription
name*StringName of the badge. Ex: 10% off on watches.
Badge name should be unique and is case sensitive.
descriptionStringBrief description of the badge. Ex: Purchase 2 watches get a $100 voucher.
startOn*Date TimeTimestamp indicating when the badge starts.
Timestamp in epoch time.
expiresOn*Date TimeTimestamp indicating when the badge ends.
Timestamp in epoch time.
earnedBadgeExpiry*ObjectObject containing details about the expiry of earned badges.
expiryType*EnumType of badge expiry.
Supported values: "RELATIVE","ABSOLUTE","NEVER"
Relative expiry: Based on when the badge was issued.
Absolute expiry: Based on the fixed date from the badge issual.
Never: The badges will never expire after issual.
When the expiryType of the badge is set to NEVER, then the badge expiry is set to 100 years from now.
type*EnumType refers to the badge expiration method based on fixed date or badge_meta.
Supported values: WITH_BADGE_META, FIXED_DATE

1f. WITH_BADGE_META: The expiry of the badge is based on the mandatory expiresOn parameter.
2. FIXED_DATE: The expiry of the badge is based on the expiry date of the incentives associated with the badge.
expiresOnDateTimestamp indicating when the badge expires. It is mandatory to pass this expiresOn parameter when FIXED_DATE is chosen.
expireWithBadgeMeta*BooleanIndicates if the badge should expire based on the mandatory parameter expiresOn .
relativeExpiryTypeEnumExpiry type relative to the badge issue.
Supprted values:DAYS/WEEKS/MONTHS.
Applicable when expiryType is RELATIVE.
ownership*ObjectAn object containing ownership restrictions.

You cannot remove an owner if it has an active badge claim associated with it. For example, you cannot remove Loyalty as the owner if there is an active badge associated with it.
restrictedToOwners*Object List of owner categories that are allowed to claim the badge. The owner indicates the module where the badge will be used.
Supported values: Loyalty, Loyalty_Promotion, Referral_Campaigns, Journeys, Audience_Campaigns, Rewards_Catalog, Goodwill_Module, Milestones, Historical_Import
customerConstraintsArrayList of constraints specific to customers. This is applicable when earnType is EARN
constraintTypeEnumType of customer constraint. Customer constraints are the restrictions applied by the brands to have control on the issuals of badges to a particular customer.
Supported values: "CUSTOMER_BADGE_FIXED_WINDOW" , "CUSTOMER_BADGE_FIXED_VALUE", "CUSTOMER_BADGE_ROLLING_WINDOW" and "CUSTOMER_BADGE_NO_LIMIT".

CUSTOMER_BADGE_FIXED_WINDOW: Refers to the fixed earn limit for the customer.
In this constraint type, the system creates fixed windows based on the duration type chosen, during this time frame the customer can earn the badge.

CUSTOMER_BADGE_ROLLING_WINDOW refers to the customer's earning limit calculated over a certain period in the past day/week/month.
durationTypeEnumDuration of the badge constraint. Supported values: DAILY, WEEKLY, MONTHLY.
If durationType is set to Daily, refreshRate is a mandatory parameter. The system will create daily windows for the duration of the promotion.

If durationType is set to Weekly, startDayOfTheWeek becomes a mandatory parameter, default value: Monday.
For weekly, the system creates cycles as per the logic given below:

- Badge start date - 25 Sep

- Badge end date - 30 Oct
- Limit cycles will be 25 Sep - 1 Oct, 2 Oct - 8 Oct, 9 Oct - 15 Oct. So on till 30 Oct.
refreshRateIntegerRefers to the number of days the fixed window duration is.
startDayOfTheWeekEnumDay on which the cycle starts. Supported values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
maxEarnLimitIntegerThe maximum limit a customer can earn during the week.
maxEarnForDaysIntegerMaximum earning limit per day
This is applicable for CUSTOMER_BADGE_ROLLING_WINDOW.
rollForDaysIntegerThe number of days for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
maxEarnForWeeksIntegerMaximum earning limit per week. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
rollForWeeksIntegerNumber of weeks for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
maxEarnForMonthsIntegerMaximum earning limit per month. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
rollForMonthsIntegerNumber of months for rolling calculation. Applicable only when CUSTOMER_BADGE_ROLLING_WINDOW is opted.
badgeConstraintsArrayRestrictions that are applied on the badge.
This is applicable when issue type is EARN.
constraintTypeEnumType of badge constraint. Badge constraints are the restrictions applied by the brands on the badges to create a limit the overall badges that can be issued to customer.

Supported values: "BADGE_FIXED_WINDOW", "BADGE_ROLLING_WINDOW", "BADGE_FIXED_VALUE","BADGE_NO_LIMIT".
BADGE_FIXED_WINDOW refers to the fixed earn limit of the badge. The system will create fixed windows based on the duration type chosen.
BADGE_ROLLING_WINDOW refers to the badge earn limit calculated over a certain period in the past day/week/month.
durationTypeEnumDuration of the badge constraint. Supported values: DAILY, WEEKLY, MONTHLY.
If durationType is set to Daily, refreshRate is a mandatory parameter. The system will create daily windows for the duration of the promotion.

If durationType is set to Weekly, startDayOfTheWeek becomes a mandatory parameter, default value: Monday.
For weekly, the system will create cycles as per the logic given below:

- Badge start date - 25 Sep
- Badge end date - 30 Oct
- Limit cycles will be 25 Sep - 1 Oct, 2 Oct - 8 Oct, 9 Oct - 15 Oct. So on till 30 Oct.
refreshRateIntegerRefers to the number of days the fixed window duration is.
startDayOfTheWeekEnumDay on which the cycle starts. Supported values: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
maxEarnLimitIntegerThe maximum limit a customer can earn during the period.
rollTypeEnumTimeframe of the rolling window.
Supprted values:DAYS/WEEKS/MONTHS
rollValueIntegerValue for rolling window calculation.
maxEarnLimitIntegerMaximum limit a badge can earn.
earnType*EnumThe method 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: The Badges are issued directly to the customer who fulfills the earn condition (no enrolment to badges-related program).
Note: If the earnType is ISSUE_EARN, use the request body, Issue Earn Type tab below.
benefitsArrayList of benefits associated with the badge.
benefitTypeEnumType of benefit linked to the badge. Promotions and gift vouchers should be linked exclusively to loyalty type (Direct Issue).
Supported values: COUPON, LOYALTY_POINTS, CART_PROMOTION, GIFT_VOUCHER.
NOTE: Same promotion ID cannot be used for more than one benefitType. Promotions or gift vouchers associated with loyalty_earning, POS transactions, rewards, or code-linked types are not permitted.
seriesIdIntegerSeries ID for the benefit. This is applicable for COUPON benefits.
promotionIdStringPromotion ID for benefit. This is applicable for CART_PROMOTION, GIFT_VOUCHER benefits.
pointsIntegerLoyalty points associated with the benefit.
This is applicable for LOYALTY_POINTS benefits.
programId*IntegerProgram ID for loyalty points
This is applicable for LOYALTY_POINTS benefits.
promotionId*IntegerPromotion ID for loyalty points
This is applicable for LOYALTY_POINTS benefits.
allocationStrategyId*IntegerAllocation strategy ID. Points allocation allows you to award points to customers based on certain activities.
This is applicable for LOYALTY_POINTS benefits.
expirationStrategyId*IntegerExpiration strategy ID.
This is applicable for LOYALTY_POINTS benefits.
tagsArrayProvides the details of the tags that are attached to the badges during creation of the badge. Tags are used to store additional information about the badge which can help to identify or categorize the badge.
nameStringName of the tag.
valueStringValue of the tag.
active*BooleanIndicates whether the badge is currently active.
customFieldsObjectList of custom fields.
customFieldNameStringName of the custom field
customFieldValueStringValue of the custom field.
badgeGroupIdStringUnique group ID associated with the badge.
To add the badge to a group, pass badgeGroupId value.
badgeRankIntegerBadge 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.
{
    "name": "BADGE12",
    "description": "Purchase 5 pet products in 3 months and get a pet grooming voucher",
    "startOn": 1716803487,
    "expiresOn": 1726804000,
    "badgeRank": 1,
    "earnedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "WITH_BADGE_META",
        "expireWithBadgeMeta": true
    },
    "ownership": {
        "restrictedToOwners": [
            "Loyalty",
            "Milestones"
        ]  
    },
    "customerConstraints": [
        {
			"constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "durationType": "DAYS",
                "refreshRate": 3,
                "startDayOfTheWeek": "TUESDAY",
                "maxEarnLimit": 1
        }
    ],
    "badgeConstraints": [
           {
      		"constraintType": "BADGE_FIXED_WINDOW",
      		"maxEarnLimit": 2,
      		"durationType":"DAYS",
      		"refreshRate":3,
      		"startDayOfTheWeek":1
   		 }
    ],
    "earnType": "EARN",
    "benefits": [
        {
            "benefitType": "COUPON",
            "seriesId": 13686
        },
        {
            "benefitType": "COUPON",
            "seriesId": 1234
        },
        {
            "benefitType": "COUPON",
            "seriesId": 6789
        },
        {
            "benefitType": "LOYALTY_POINTS",
            "points": 100,
            "programId": 626,
            "promotionId": 80332,
            "allocationStrategyId": 1489,
            "expirationStrategyId": 3843
        }
    ],
    "tags": [
        {
            "name": "Type1",
            "value": "Birthday"
        },
        {
            "name": "Priority",
            "value": "1"
        },
        {
            "name": "category",
            "value": "rare"
        }
    ],
    "active": false
}
{
    "name": "Badge Issue earn",
    "description": "Make 5 transactions",
    "startOn": 1716803487,
    "expiresOn": 1726804000,
     "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"
        ]
    },
    "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
        }
    ]
}
{
    "name": "Badge_Earn",
    "description": "Purchase 5 pet products in 3 months and get a pet grooming voucher",
    "startOn": 1716803487,
    "expiresOn": 1726804000,
    "earnedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "WITH_BADGE_META",
        "expireWithBadgeMeta": true
    },
    "ownership": {
        "restrictedToOwners": [
            "Loyalty",
            "Milestones"
        ]   
    },
    "customerConstraints": [
        {
            "constraintType": "CUSTOMER_BADGE_FIXED_VALUE",
            "maxEarnLimit": 100
        }
    ],
    "badgeConstraints": [
           {
      		"constraintType": "BADGE_FIXED_WINDOW",
      		"maxEarnLimit": 2,
      		"durationType":"DAYS",
      		"refreshRate":3,
      		"startDayOfTheWeek":1
   		 }
    ],
    "earnType": "EARN",
    "benefits": [
        {
            "benefitType": "COUPON",
            "seriesId": 13686
        },
        {
            "benefitType": "COUPON",
            "seriesId": 1234
        },
        {
            "benefitType": "COUPON",
            "seriesId": 6789
        },
        {
            "benefitType": "LOYALTY_POINTS",
            "points": 100,
            "programId": 626,
            "promotionId": 80332,
            "allocationStrategyId": 1489,
            "expirationStrategyId": 3843
        }
    ],
    "tags": [
        {
            "name": "Type1",
            "value": "Birthday"
        },
        {
            "name": "Priority",
            "value": "1"
        },
        {
            "name": "category",
            "value": "rare"
        }
    ],
    "active": false
}
{
    "name": "Badge_Issue_earntype",
    "description": "Make 5 transactions in a month, get a badge and 10% off coupon",
    "startOn": 1716803487,
    "expiresOn": 1726804000,
     "earnType": "ISSUE_EARN",
    "earnedBadgeExpiry": {
        "relativeExpirytype": "WEEKS",
        "value": 2,
        "expiryType": "RELATIVE"
    },
    "issuedBadgeExpiry": {
        "type": "FIXED_DATE",
        "expiresOn": 1926235957,
        "expiryType": "ABSOLUTE"
    },
    "isActive": true,
    "ownership": {
        "restrictedToOwners": [
            "Loyalty",
            "Audience_Campaigns"
        ]
    },
    "benefits": [
        {
            "benefitType": "COUPON",
            "seriesId": 13745
        }
    ],
    "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": 10000
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "DAYS",
            "rollValue": 1,
            "maxEarnLimit": 300
        },
        {
            "constraintType": "BADGE_ROLLING_WINDOW",
            "rollType": "WEEKS",
            "rollValue": 1,
            "maxEarnLimit": 3000
        }
    ]
}
{
    "name": "test6578791",
    "description": "Purchase 5 pet products in 3 months and get a pet grooming voucher",
    "startOn": 1799632870,
    "expiresOn": 1828754110,
    "earnedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "WITH_BADGE_META",
        "expireWithBadgeMeta": true
    },
    "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": 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
        }
    ],
    "earnType": "EARN",
    "benefits": [
        {
            "benefitType": "COUPON",
            "seriesId": 13686
        },
        {
            "benefitType": "COUPON",
            "seriesId": 1234
        },
        {
            "benefitType": "COUPON",
            "seriesId": 6789
        },
        {
            "benefitType": "LOYALTY_POINTS",
            "points": 100,
            "programId": 626,
            "promotionId": 80332,
            "allocationStrategyId": 1489,
            "expirationStrategyId": 3843
        }
    ],
    "tags": [
        {
            "name": "Type1",
            "value": "Birthday"
        },
        {
            "name": "Priority",
            "value": "1"
        },
        {
            "name": "category",
            "value": "rare"
        }
    ],
    "customFields": {
      "CF1" : "CF1",
      "CF2 INTEGER" : "1"
     },
    "active": false
}
{
    "orgId": 50933,
    "name": "demo testkerl2n26df132",
    "description": "string",
    "startOn": "2023-11-14T21:51:00.192Z",
    "expiresOn": "2026-12-03T15:19:37.192Z",
    "earnedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "WITH_BADGE_META",
        "expiresOn": "2024-11-03T15:19:37.192Z",
        "expireWithBadgeMeta": true
    },
    "issuedBadgeExpiry": {
        "expiryType": "ABSOLUTE",
        "type": "WITH_BADGE_META",
        "expiresOn": "2024-11-03T15:19:37.192Z",
        "expireWithBadgeMeta": true
    },
    "images": [
        {
            "name": "string",
            "fileSvcHandle": "string",
            "url": "string",
            "tag": "UN_EARNED"
        }
    ],
    "ownership": {
        "restrictedToOwners": [
            "Loyalty"
        ],
        "claims": [
            {
                "badgeMetaId": "string",
                "ownerType": "Loyalty",
                "referenceId": "string"
            }
        ]
    },
    "customerConstraints": [
        {
            "constraintType": "BADGE_NO_LIMIT",
            "maxEarnLimit": 0
        },
        {
            "constraintType": "BADGE_NO_LIMIT",
            "maxEarnLimit": 0
        },
        {
            "constraintType": "BADGE_NO_LIMIT"
        },
        {
            "constraintType": "BADGE_NO_LIMIT"
        },
        {
            "constraintType": "BADGE_NO_LIMIT",
            "rollType": "DAYS",
            "rollValue": 0,
            "maxEarnLimit": 0
        },
        {
            "constraintType": "BADGE_NO_LIMIT",
            "maxEarnForDays": 0,
            "rollForDays": 0,
            "maxEarnForWeeks": 0,
            "rollForWeeks": 0,
            "maxEarnForMonths": 0,
            "rollForMonths": 0
        }
    ],
    "badgeConstraints": [
        {
            "constraintType": "BADGE_NO_LIMIT",
            "maxEarnLimit": 0
        },
        {
            "constraintType": "BADGE_NO_LIMIT",
            "maxEarnLimit": 0
        },
        {
            "constraintType": "BADGE_NO_LIMIT"
        },
        {
            "constraintType": "BADGE_NO_LIMIT"
        },
        {
            "constraintType": "BADGE_NO_LIMIT",
            "rollType": "DAYS",
            "rollValue": 0,
            "maxEarnLimit": 0
        },
        {
            "constraintType": "BADGE_NO_LIMIT",
            "maxEarnForDays": 0,
            "rollForDays": 0,
            "maxEarnForWeeks": 0,
            "rollForWeeks": 0,
            "maxEarnForMonths": 0,
            "rollForMonths": 0
        }
    ],
    "benefits": [
        {
            "benefitType": "COUPON",
            "seriesId": 1
        }
    ],
    "tags": [
        {
            "name1": "string",
            "value": "string"
        }
    ],
    "earnType": "EARN",
    "issuedCount": 0,
    "earnedCount": 0,
    "status": "LIVE",
    "createdOn": "2023-11-03T15:19:37.192Z",
    "createdBy": 0,
    "lastUpdatedOn": "2023-11-03T15:19:37.192Z",
    "lastUpdatedBy": 0,
     "customFields": {
      "CF1" : "CF1",
      "CF2 INTEGER" : "1"
     },
    "active": true
}
{
  "name": "badgeName_0326",
  "description": "demoDescription",
  "startOn": "2024-02-10T00:00:37.192Z",
  "expiresOn": "2024-08-30T00:00:37.192Z",
  "earnedBadgeExpiry": {
    "expiryType": "RELATIVE",
    "relativeExpirytype": "DAYS",
    "value": 2
    },
  "issuedBadgeExpiry": {
    "expiryType": "NEVER"
  },
  "benefits": [
        {
            "benefitType": "CART_PROMOTION",
            "promotionId": "66e298e26e089949f41b3268"
        },
        {
            "benefitType": "GIFT_VOUCHER",
            "promotionId": "6666380a929a037ea21da2e2"
        }
    ],
  "images": [
    {
      "name": "string",
      "fileSvcHandle": "string",
      "url": "string",
      "tag": "UN_EARNED"
    }
  ],
  "ownership": {
    "restrictedToOwners": [
      "Loyalty_Promotion"
    ]
  },
  "tags": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "customerConstraints": [
    {
      "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
      "maxEarnLimit": 4,
      "durationType":"DAYS",
      "refreshRate":2,
      "startDayOfTheWeek":"TUESDAY"
    }
  ],
    "badgeConstraints": [
    {
      "constraintType": "BADGE_FIXED_WINDOW",
      "maxEarnLimit": 4,
      "durationType":"DAYS",
      "refreshRate":3,
      "startDayOfTheWeek":"TUESDAY"
    }
  ],
  "earnType": "EARN",
  "issuedCount": 0,
  "earnedCount": 0,
  "status": "UPCOMING",
  "createdOn": "2023-11-15T15:19:37.192Z",
  "createdBy": 0,
  "lastUpdatedOn": "2023-11-15T15:19:37.192Z",
  "lastUpdatedBy": 0,
  "active": true
}

Response parameters

ParameterDescription
dataThe main container for the response data.
idUnique identifier for the data item.
orgIdIdentifier for the organization associated with the data.
nameName of the badge.
descriptionDescription of the badge.
startOnTimestamp for when the badge starts.
expiresOnTimestamp for when the badge expires.
earnedBadgeExpiryDetails about the expiry of the earned badge.
expiryTypeType of badge expiry.
Supported values: "RELATIVE","ABSOLUTE","NEVER"
Relative expiry: Based on when the badge was issued.
Absolute expiry: Based on the fixed date from the badge issual.
Never: The badges will never expiry after issual.
typeType of expiry.
Supported values: DAYS/WEEKS/MONTHS.
Relative expiry is based on when the badge was issued.
expiresOnThe timestamp for when the badge expires.
expireWithBadgeMetaIndicates if expiry is linked with badge metadata.
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.
tagTag associated with the image.
ownershipThe module for which the badge is being created.
restrictedToOwnersLists owner categories that can claim the badge, such as "Loyalty" and "Milestones" etc.
customerConstraintsLimit on how many quantities of a badge can be given to a particular customer.
badgeConstraintsLimit on how many quantities of a reward can be given to customers
benefitsArray of benefits associated with the item.
benefitTypeType of benefit linked to the badge.
Supported values: COUPON, LOYALTY_POINTS, CART_PROMOTION, GIFT_VOUCHER.
seriesIdIdentifier for the series of the benefit.
tagsCustom metadata tagged to the reward used for auditing and reporting purposes
badgeGroupIdUnique group ID associated with the badge.
badgeRankBadge rank is the rank within a group, user can define the badge rank even if group is not linked with the badge.
earnTypeThe method 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: The 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: The badges which are in live state and can be earned.
UPCOMING: The badges which are upcoming on a further date.
EXPIRED/ENDED: The badges which have expired and cannot be earned.
createdOnTimestamp for when the badge was created.
createdByIdentifier of the user who created the badge.
lastUpdatedOnTimestamp for the last update made to the badge.
lastUpdatedByIdentifier of the user who last updated the badge.
activeIndicates whether the badge is active or not.
errorsContains details of any errors.
warningsContains details of any warnings.
{
    "data": {
        "id": "662749408fe258516a88fe89",
        "orgId": 100458,
        "name": "BADGE123",
        "description": "Purchase 5 pet products in 3 months and get a pet grooming voucher",
        "startOn": 1716803487.000000000,
        "expiresOn": 1726804000.000000000,
        "earnedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "WITH_BADGE_META",
            "expiresOn": null,
            "expireWithBadgeMeta": true
        },
        "issuedBadgeExpiry": null,
        "images": [],
        "ownership": {
            "restrictedToOwners": [
                "Milestones",
                "Loyalty"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "e6791ec9-e92f-34af-bdc3-be2607fdf82c",
                "durationType": "DAYS",
                "refreshRate": 3,
                "maxEarnLimit": 1,
                "cycleStatus": "UPCOMING",
                "startDate": 1716803487.000000000,
                "endDate": 1726804000.000000000
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_WINDOW",
                "referenceId": "a1350b49-eb8e-3500-9e43-01f5493c91c1",
                "durationType": "DAYS",
                "refreshRate": 3,
                "maxEarnLimit": 2,
                "startDate": 1716803487.000000000,
                "endDate": 1726804000.000000000,
                "cycleStatus": "UPCOMING"
            }
        ],
        "benefits": [
            {
                "benefitType": "COUPON",
                "seriesId": 6789
            },
            {
                "benefitType": "COUPON",
                "seriesId": 13686
            },
            {
                "benefitType": "LOYALTY_POINTS",
                "programId": 626,
                "promotionId": 80332,
                "allocationStrategyId": 1489,
                "expirationStrategyId": 3843,
                "defaultTillId": null
            },
            {
                "benefitType": "COUPON",
                "seriesId": 1234
            }
        ],
        "tags": [
            {
                "name": "Type1",
                "value": "Birthday"
            },
            {
                "name": "category",
                "value": "rare"
            },
            {
                "name": "Priority",
                "value": "1"
            }
        ],
        "badgeGroupId": null,
        "badgeRank": 1,
        "earnType": "EARN",
        "status": "UPCOMING",
        "createdOn": 1713850688.811401000,
        "createdBy": 75086856,
        "lastUpdatedOn": 1713850688.811401000,
        "lastUpdatedBy": 75086856,
        "customFields": {},
        "active": false
    },
    "errors": [],
    "warnings": []
}
{
    "data": {
        "id": "662748a08fe258516a88fe88",
        "orgId": 100458,
        "name": "Badge Issue earn",
        "description": "Make 5 transactions",
        "startOn": 1716803487.000000000,
        "expiresOn": 1726804000.000000000,
        "earnedBadgeExpiry": {
            "expiryType": "RELATIVE",
            "relativeExpirytype": "WEEKS",
            "value": 2
        },
        "issuedBadgeExpiry": {
            "expiryType": "ABSOLUTE",
            "type": "FIXED_DATE",
            "expiresOn": 1926235957.000000000,
            "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": [
                "Audience_Campaigns",
                "Loyalty"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "e6791ec9-e92f-34af-bdc3-be2607fdf82c",
                "durationType": "DAYS",
                "refreshRate": 3,
                "maxEarnLimit": 2,
                "cycleStatus": "UPCOMING",
                "startDate": 1716803487.000000000,
                "endDate": 1926235957.000000000
            }
        ],
        "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": [
            {
                "benefitType": "COUPON",
                "seriesId": 13745
            }
        ],
        "tags": [],
        "badgeGroupId": null,
        "badgeRank": 3,
        "earnType": "ISSUE_EARN",
        "status": "UPCOMING",
        "createdOn": 1713850528.634380000,
        "createdBy": 75086856,
        "lastUpdatedOn": 1713850528.634380000,
        "lastUpdatedBy": 75086856,
        "customFields": {},
        "active": true
    },
    "errors": [],
    "warnings": []
}
{
    "data": {
        "id": "66e9563ff0210a1952fee2b8",
        "badgeNumericId": 29,
        "orgId": 50371,
        "name": "badgeName_0326",
        "description": "demoDescription",
        "startOn": 1707523237.192000000,
        "expiresOn": 1724976037.192000000,
        "earnedBadgeExpiry": {
            "expiryType": "RELATIVE",
            "relativeExpirytype": "DAYS",
            "value": 2
        },
        "issuedBadgeExpiry": {
            "expiryType": "NEVER"
        },
        "images": [
            {
                "name": "string",
                "fileSvcHandle": "string",
                "url": "string",
                "tag": "UN_EARNED"
            }
        ],
        "ownership": {
            "restrictedToOwners": [
                "Loyalty_Promotion"
            ],
            "claims": []
        },
        "customerConstraints": [
            {
                "constraintType": "CUSTOMER_BADGE_FIXED_WINDOW",
                "referenceId": "31c21398-2ef5-3922-a08d-b1144c6b3464",
                "durationType": "DAYS",
                "refreshRate": 2,
                "maxEarnLimit": 4,
                "cycleStatus": "ACTIVE",
                "startDate": 1707523237.192000000,
                "endDate": 4880649637.192000000
            }
        ],
        "badgeConstraints": [
            {
                "constraintType": "BADGE_FIXED_WINDOW",
                "referenceId": "a1350b49-eb8e-3500-9e43-01f5493c91c1",
                "durationType": "DAYS",
                "refreshRate": 3,
                "maxEarnLimit": 4,
                "startDate": 1707523237.192000000,
                "endDate": 4880649637.192000000,
                "cycleStatus": "ACTIVE"
            }
        ],
        "benefits": [
            {
                "benefitType": "GIFT_VOUCHER",
                "promotionId": "6666380a929a037ea21da2e2"
            },
            {
                "benefitType": "CART_PROMOTION",
                "promotionId": "66e298e26e089949f41b3268"
            }
        ],
        "tags": [
            {
                "name": "string",
                "value": "string"
            }
        ],
        "badgeGroupId": null,
        "badgeRank": null,
        "earnType": "EARN",
        "status": "EXPIRED",
        "createdOn": 1726567999.336216000,
        "createdBy": 50022820,
        "lastUpdatedOn": 1726567999.336216000,
        "lastUpdatedBy": 50022820,
        "customFields": {},
        "active": true
    },
    "errors": [],
    "warnings": []
}
{
    "data": null,
    "errors": [
        {
            "code": 728,
            "message": "Atleast one owner is required",
            "reference": "ownership.restrictedToOwners"
        },
        {
            "code": 725,
            "message": "Badge name cannot be duplicate",
            "reference": null
        },
        {
            "code": 722,
            "message": "Start Date cannot be past date",
            "reference": null
        },
        {
            "code": 714,
            "message": "Owner type is not allowed.",
            "reference": "ownership.restrictedToOwners"
        }
    ],
    "warnings": null
}

API-specific error codes

Error codeDescription
714Owner type is not allowed.
722Start date cannot be past date.
725Badge name cannot be duplicated.
728At least one owner is required.
999999HV000028: Unexpected exception during isValid call.
Language
Authorization
Basic
base64
:
URL
Click Try It! to start a request and see the response here!