REST API v2
API references
Tiers

Tiers

Tier management

Get all tiers

GET/rest_api/v2/tiers

Retrieve all customer tiers for the authenticated shop

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Responses
200List of tiers
successbooleanOptional
Example: true
dataTier[]Optional
Show properties
idstringOptional

Tier ID

Example: "0cd20cc6-1cac-40fe-b350-49deca03470d"
namestringOptional

Tier name

Example: "VIP - PRO"
iconstringOptional

Default icon URL

Example: "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png"
iconCustomstringOptional

Custom icon URL

Example: ""
targetPointintegerOptional

Points required to reach this tier

Example: 5000
targetPointUpdateintegerOptional

Updated points required

Example: 5000
membersintegerOptional

Number of customers in this tier

Example: 42
placedOrderRewardbooleanOptional

Whether tier has place order rewards

Example: false
rateMoneynumberOptional

Money rate for earning points

Example: 1
earnPointintegerOptional

Points earning configuration

Example: 1
shopIdstringOptional

Shop ID

Example: "umN0f3GKyQC3XS1AwVWg"
imageBlockstringOptional

Image block URL

Example: "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png"
tierRewardsTierReward[]Optional

Tier-specific rewards/benefits

Example: []
Show properties
idstringOptional

Reward ID

Example: "FNSGeIIRYIagQR9ysmD3"
statusbooleanOptional

Whether reward is active

Example: true
titlestringOptional

Reward title

Example: "Points for discounts"
redeemTypestringOptional

Type of redemption

Example: "fixed"
spendPointintegerOptional

Points required to redeem

Example: 100
minSpendPointstringOptional

Minimum points to spend

Example: ""
maxSpendPointstringOptional

Maximum points to spend

Example: ""
appliedTostringOptional

Where reward applies

Example: "all"
orderReqstringOptional

Order requirements

Example: "none"
orderReqAmountnumberOptional

Minimum order amount required

Example: 0
expiredAfterstringOptional

When reward expires

Example: "permanent"
expiredTimestring · date-timeOptional

Specific expiration time

Example: "2025-06-02T07:35:16.908Z"
typestringOptional

Reward type

Example: "tier_privileges"
codeNamestringOptional

Code name for reward

Example: "Discount"
earnAmountstringOptional

Amount earned

Example: "1"
eventstringOptional

Event type for reward

Example: "bonus_point"
bonusPointsstringOptional

Bonus points awarded

Example: "1"
priorityintegerOptional

Reward priority

Example: 0
showLoyaltyPagebooleanOptional

Whether to show on loyalty page

Example: true
translateTitleobjectOptional

Translated titles for different languages

Example: {"vi":"Points for discounts (Vietnamese)","ar":"Points for discounts (Arabic)"}
expiredbooleanOptional

Whether reward has expired

Example: false
createdAtstring · date-timeOptional

Reward creation timestamp

Example: "2025-06-02T07:47:49.623Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-18T08:13:55.794Z"
inactivebooleanOptional

Whether tier is inactive

Example: false
isExclusiveTierbooleanOptional

Whether tier is exclusive

Example: false
prevNamesstring[]Optional

Previous names of this tier

Example: []
createdAtstring · date-timeOptional

Tier creation timestamp

Example: "2024-01-15T10:30:00.000Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2024-01-20T14:45:30.000Z"
metaobjectOptional
Show properties
countintegerOptional

Number of items returned

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
401Authentication required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
403Plan upgrade required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
500Internal server error
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/tiers
GET /rest_api/v2/tiers HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200List of tiers
{
  "success": true,
  "data": [
    {
      "id": "0cd20cc6-1cac-40fe-b350-49deca03470d",
      "name": "VIP - PRO",
      "icon": "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png",
      "targetPoint": 0,
      "members": 0,
      "isSystemTier": false,
      "isExclusiveTier": true,
      "textColor": "#785F4D",
      "boxBgColor": "#EAD8C0",
      "tierRewards": [],
      "createdAt": "2024-12-05T07:39:18.085Z",
      "updatedAt": "2025-06-12T10:29:00.304Z"
    },
    {
      "id": "1Fe1kqHZbE7Alx1GmFEC",
      "name": "Bronze - 1",
      "icon": "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png",
      "targetPoint": 0,
      "members": 0,
      "isSystemTier": true,
      "systemType": "bronze",
      "textColor": "#785F4D",
      "boxBgColor": "#EAD8C0",
      "tierRewards": [
        {
          "id": "FNSGeIIRYIagQR9ysmD3",
          "status": true,
          "title": "Points for discounts",
          "redeemType": "fixed",
          "spendPoint": 100,
          "type": "tier_privileges",
          "showLoyaltyPage": true,
          "expired": false,
          "createdAt": "2025-06-02T07:47:49.623Z",
          "updatedAt": "2025-06-18T08:13:55.794Z"
        }
      ],
      "createdAt": "2023-12-20T04:15:11.202Z",
      "updatedAt": "2025-06-05T08:09:18.273Z"
    }
  ]
}

Create a new tier

POST/rest_api/v2/tiers

Creates a new VIP tier. Optionally include a rewards array to create tier rewards inline with the tier.

Constraints:

  • Tier name must be unique (409 if duplicate)
  • targetPoint is required and must be ≥ 0

Side effects: publishApp() triggered after creation.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request body
namestringRequired

Tier name (must be unique)

targetPointintegerRequired

Points required to reach this tier

targetPointUpdateintegerOptional

Defaults to targetPoint if not provided

iconstringOptional

Icon ID (tier_bronze_icon, tier_sliver_icon, tier_gold_icon, tier_diamond_icon, tier_platinum_icon, tier_crown_icon)

iconCustomstringOptional

Custom icon URL

hideDefaultTierbooleanOptional
isExclusiveTierbooleanOptional
tierNamesLanguageobjectOptional

Multi-language tier names {locale: name}

textColorstringOptional

Hex color

progressBarColorstringOptional
boxBgColorstringOptional
boxTextColorstringOptional
bgCardColorstringOptional
cardOpacitynumberOptional
iconColorstringOptional
bgTypestringOptional
rewardsTierRewardCreate[]Optional

Inline rewards to create with the tier

Show properties
eventstringRequired

Reward event type

titlestringRequired

Reward name

typestringOptional
earnAmountstringOptional

Discount amount/percentage. For free_gift always '100'

spendPointstringOptional

Points required to redeem

bonusPointsstringOptional

Bonus points (for bonus_point event, ≥1)

codeNamestringOptional

Code name (for privilege rewards)

appliedTostringOptional
orderReqstringOptional
orderReqAmountstringOptional
specificProductsobject[]Optional

Product list (max 1 for free_gift)

specificCollectionsstring[]Optional
combinedWithstring[]Optional
hasLimitShippingbooleanOptional
limitShippingnumberOptional
expiredAfternumberOptional
expiredUnitstringOptional
statusbooleanOptional
Responses
201Tier created
successbooleanOptional
Example: true
dataTierOptional

Customer tier with all fields that may be returned by the API. Note: Actual responses may only include non-null fields due to automatic filtering.

Show properties
idstringOptional

Tier ID

Example: "0cd20cc6-1cac-40fe-b350-49deca03470d"
namestringOptional

Tier name

Example: "VIP - PRO"
iconstringOptional

Default icon URL

Example: "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png"
iconCustomstringOptional

Custom icon URL

Example: ""
targetPointintegerOptional

Points required to reach this tier

Example: 5000
targetPointUpdateintegerOptional

Updated points required

Example: 5000
membersintegerOptional

Number of customers in this tier

Example: 42
placedOrderRewardbooleanOptional

Whether tier has place order rewards

Example: false
rateMoneynumberOptional

Money rate for earning points

Example: 1
earnPointintegerOptional

Points earning configuration

Example: 1
shopIdstringOptional

Shop ID

Example: "umN0f3GKyQC3XS1AwVWg"
imageBlockstringOptional

Image block URL

Example: "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png"
tierRewardsTierReward[]Optional

Tier-specific rewards/benefits

Example: []
Show properties
idstringOptional

Reward ID

Example: "FNSGeIIRYIagQR9ysmD3"
statusbooleanOptional

Whether reward is active

Example: true
titlestringOptional

Reward title

Example: "Points for discounts"
redeemTypestringOptional

Type of redemption

Example: "fixed"
spendPointintegerOptional

Points required to redeem

Example: 100
minSpendPointstringOptional

Minimum points to spend

Example: ""
maxSpendPointstringOptional

Maximum points to spend

Example: ""
appliedTostringOptional

Where reward applies

Example: "all"
orderReqstringOptional

Order requirements

Example: "none"
orderReqAmountnumberOptional

Minimum order amount required

Example: 0
expiredAfterstringOptional

When reward expires

Example: "permanent"
expiredTimestring · date-timeOptional

Specific expiration time

Example: "2025-06-02T07:35:16.908Z"
typestringOptional

Reward type

Example: "tier_privileges"
codeNamestringOptional

Code name for reward

Example: "Discount"
earnAmountstringOptional

Amount earned

Example: "1"
eventstringOptional

Event type for reward

Example: "bonus_point"
bonusPointsstringOptional

Bonus points awarded

Example: "1"
priorityintegerOptional

Reward priority

Example: 0
showLoyaltyPagebooleanOptional

Whether to show on loyalty page

Example: true
translateTitleobjectOptional

Translated titles for different languages

Example: {"vi":"Points for discounts (Vietnamese)","ar":"Points for discounts (Arabic)"}
expiredbooleanOptional

Whether reward has expired

Example: false
createdAtstring · date-timeOptional

Reward creation timestamp

Example: "2025-06-02T07:47:49.623Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-18T08:13:55.794Z"
inactivebooleanOptional

Whether tier is inactive

Example: false
isExclusiveTierbooleanOptional

Whether tier is exclusive

Example: false
prevNamesstring[]Optional

Previous names of this tier

Example: []
createdAtstring · date-timeOptional

Tier creation timestamp

Example: "2024-01-15T10:30:00.000Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2024-01-20T14:45:30.000Z"
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
400Validation error
No body
409Tier name already exists (TIER_NAME_DUPLICATE)
No body
POST/rest_api/v2/tiers
POST /rest_api/v2/tiers HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 133


{
  "name": "Platinum",
  "targetPoint": 1000,
  "icon": "tier_platinum_icon",
  "textColor": "#FFFFFF",
  "bgCardColor": "#1A1A2E"
}
201Tier created
{
  "success": true,
  "data": {
    "id": "0cd20cc6-1cac-40fe-b350-49deca03470d",
    "name": "VIP - PRO",
    "icon": "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png",
    "iconCustom": "",
    "targetPoint": 5000,
    "targetPointUpdate": 5000,
    "members": 42,
    "placedOrderReward": false,
    "rateMoney": 1,
    "earnPoint": 1,
    "shopId": "umN0f3GKyQC3XS1AwVWg",
    "imageBlock": "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png",
    "tierRewards": [],
    "inactive": false,
    "isExclusiveTier": false,
    "prevNames": [],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:45:30.000Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get global tier settings

GET/rest_api/v2/tiers/settings

Returns the global VIP tier program settings (entry method, demotion, reset cycle, tags, etc.). This is a single document per shop.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Responses
200Tier settings
successbooleanOptional
Example: true
dataTierSettingsOptional

Global VIP tier program settings

Show properties
idstringOptional
statusbooleanOptional

Tier program active (read-only via API, requires launch)

entryMethodstringOptional

How customers qualify for tiers (read-only via API)

milestonestringOptional

Reset cycle (read-only via API)

progressionTypestringOptional

Points progression type (read-only via API)

startDatestringOptional

Program start date (read-only via API)

prefixstringOptional

Discount code prefix

Example: "JOY-"
isUsePrefixDiscountCodebooleanOptional
useDemotionTierbooleanOptional

Enable tier demotion

typeDemotionstringOptional
downgradeAfterstringOptional

Duration before downgrade

Example: "6"
downgradeAfterUnitstringOptional
useResetTierbooleanOptional
monthResetTierstringOptional
Example: "12"
dayResetTierstringOptional
Example: "31"
isSyncTagsCustomerTierbooleanOptional

Auto-tag customers in Shopify by tier

customerTierTagPrefixstringOptional
Example: "joy-vip-"
notificationDowngradeBeforestringOptional
Example: "7"
notificationDowngradeBeforeUnitstringOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/tiers/settings
GET /rest_api/v2/tiers/settings HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Tier settings
{
  "success": true,
  "data": {
    "id": "string",
    "status": true,
    "entryMethod": "pointEarned",
    "milestone": "lifetime",
    "progressionType": "cumulative",
    "startDate": "string",
    "prefix": "JOY-",
    "isUsePrefixDiscountCode": true,
    "useDemotionTier": true,
    "typeDemotion": "downgrade_tier",
    "downgradeAfter": "6",
    "downgradeAfterUnit": "day",
    "useResetTier": true,
    "monthResetTier": "12",
    "dayResetTier": "31",
    "isSyncTagsCustomerTier": true,
    "customerTierTagPrefix": "joy-vip-",
    "notificationDowngradeBefore": "7",
    "notificationDowngradeBeforeUnit": "day"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update tier settings (safe fields only)

PUT/rest_api/v2/tiers/settings

Updates global tier program settings. Only safe fields are accepted — fields that require tier launch (entryMethod, milestone, startDate, progressionType, status) are excluded and must be changed via admin UI.

Safe fields: demotion config, reset schedule, discount prefix, customer tags, notifications.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request body
prefixstringOptional
isUsePrefixDiscountCodebooleanOptional
useDemotionTierbooleanOptional
typeDemotionstringOptional
downgradeAfterstringOptional
downgradeAfterUnitstringOptional
useResetTierbooleanOptional
resetAfterstringOptional
resetAfterUnitstringOptional
monthResetTierstringOptional
dayResetTierstringOptional
isSyncTagsCustomerTierbooleanOptional
customerTierTagPrefixstringOptional
notificationDowngradeBeforestringOptional
notificationDowngradeBeforeUnitstringOptional
Responses
200Updated tier settings
No body
400No valid fields provided
No body
404Tier settings not found (tiers never launched)
No body
PUT/rest_api/v2/tiers/settings
PUT /rest_api/v2/tiers/settings HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 123


{
  "useDemotionTier": true,
  "typeDemotion": "downgrade_tier",
  "downgradeAfter": "6",
  "downgradeAfterUnit": "month"
}

Get tier by ID

GET/rest_api/v2/tiers/{tierId}
Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
tierIdpath · stringRequired

Tier ID

Responses
200Tier details
successbooleanOptional
Example: true
dataTierOptional

Customer tier with all fields that may be returned by the API. Note: Actual responses may only include non-null fields due to automatic filtering.

Show properties
idstringOptional

Tier ID

Example: "0cd20cc6-1cac-40fe-b350-49deca03470d"
namestringOptional

Tier name

Example: "VIP - PRO"
iconstringOptional

Default icon URL

Example: "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png"
iconCustomstringOptional

Custom icon URL

Example: ""
targetPointintegerOptional

Points required to reach this tier

Example: 5000
targetPointUpdateintegerOptional

Updated points required

Example: 5000
membersintegerOptional

Number of customers in this tier

Example: 42
placedOrderRewardbooleanOptional

Whether tier has place order rewards

Example: false
rateMoneynumberOptional

Money rate for earning points

Example: 1
earnPointintegerOptional

Points earning configuration

Example: 1
shopIdstringOptional

Shop ID

Example: "umN0f3GKyQC3XS1AwVWg"
imageBlockstringOptional

Image block URL

Example: "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png"
tierRewardsTierReward[]Optional

Tier-specific rewards/benefits

Example: []
Show properties
idstringOptional

Reward ID

Example: "FNSGeIIRYIagQR9ysmD3"
statusbooleanOptional

Whether reward is active

Example: true
titlestringOptional

Reward title

Example: "Points for discounts"
redeemTypestringOptional

Type of redemption

Example: "fixed"
spendPointintegerOptional

Points required to redeem

Example: 100
minSpendPointstringOptional

Minimum points to spend

Example: ""
maxSpendPointstringOptional

Maximum points to spend

Example: ""
appliedTostringOptional

Where reward applies

Example: "all"
orderReqstringOptional

Order requirements

Example: "none"
orderReqAmountnumberOptional

Minimum order amount required

Example: 0
expiredAfterstringOptional

When reward expires

Example: "permanent"
expiredTimestring · date-timeOptional

Specific expiration time

Example: "2025-06-02T07:35:16.908Z"
typestringOptional

Reward type

Example: "tier_privileges"
codeNamestringOptional

Code name for reward

Example: "Discount"
earnAmountstringOptional

Amount earned

Example: "1"
eventstringOptional

Event type for reward

Example: "bonus_point"
bonusPointsstringOptional

Bonus points awarded

Example: "1"
priorityintegerOptional

Reward priority

Example: 0
showLoyaltyPagebooleanOptional

Whether to show on loyalty page

Example: true
translateTitleobjectOptional

Translated titles for different languages

Example: {"vi":"Points for discounts (Vietnamese)","ar":"Points for discounts (Arabic)"}
expiredbooleanOptional

Whether reward has expired

Example: false
createdAtstring · date-timeOptional

Reward creation timestamp

Example: "2025-06-02T07:47:49.623Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-18T08:13:55.794Z"
inactivebooleanOptional

Whether tier is inactive

Example: false
isExclusiveTierbooleanOptional

Whether tier is exclusive

Example: false
prevNamesstring[]Optional

Previous names of this tier

Example: []
createdAtstring · date-timeOptional

Tier creation timestamp

Example: "2024-01-15T10:30:00.000Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2024-01-20T14:45:30.000Z"
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
401Authentication required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
403Plan upgrade required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
404Tier not found
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
500Internal server error
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/tiers/{tierId}
GET /rest_api/v2/tiers/{tierId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Tier details
{
  "success": true,
  "data": {
    "id": "1Fe1kqHZbE7Alx1GmFEC",
    "name": "Bronze - 1",
    "icon": "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png",
    "iconCustom": "",
    "targetPoint": 0,
    "targetPointUpdate": 0,
    "members": 0,
    "placedOrderReward": false,
    "rateMoney": "",
    "earnPoint": "",
    "isSystemTier": true,
    "hideDefaultTier": false,
    "bgType": "default",
    "bgImage": "",
    "textColor": "#785F4D",
    "progressBarColor": "#785F4D",
    "boxBgColor": "#EAD8C0",
    "boxTextColor": "#785F4D",
    "bgCardColor": "#EAD8C0",
    "cardOpacity": 0,
    "iconColor": "#222222",
    "systemType": "bronze",
    "shopId": "umN0f3GKyQC3XS1AwVWg",
    "imageBlock": "https://cdnapps.avada.io/joy/vip-tiers/icons/bronze.png",
    "tierRewards": [
      {
        "id": "FNSGeIIRYIagQR9ysmD3",
        "status": true,
        "title": "Points for discounts",
        "redeemType": "fixed",
        "minSpendPoint": "",
        "maxSpendPoint": "",
        "spendPoint": 100,
        "appliedTo": "all",
        "orderReq": "none",
        "orderReqAmount": 0,
        "expiredAfter": "permanent",
        "expiredTime": "2025-06-02T07:35:16.908Z",
        "type": "tier_privileges",
        "codeName": "Discount",
        "earnAmount": "1",
        "event": "bonus_point",
        "bonusPoints": "1",
        "priority": 0,
        "showLoyaltyPage": true,
        "translateTitle": {
          "vi": "Points for discounts (Vietnamese)",
          "ar": "Points for discounts (Arabic)"
        },
        "expired": false,
        "createdAt": "2025-06-02T07:47:49.623Z",
        "updatedAt": "2025-06-18T08:13:55.794Z"
      }
    ],
    "inactive": false,
    "isExclusiveTier": false,
    "prevNames": [
      "Bronze",
      "Bronze 1",
      "Bronze 12",
      "Bronze "
    ],
    "createdAt": "2023-12-20T04:15:11.202Z",
    "updatedAt": "2025-06-05T08:09:18.273Z"
  }
}

Update a tier

PUT/rest_api/v2/tiers/{tierId}

Updates tier fields. Only whitelisted fields accepted (name, design, milestone). Tier name must be unique — returns 409 if duplicate.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
tierIdpath · stringRequired
Request body
namestringOptional
targetPointUpdateintegerOptional
iconstringOptional
iconCustomstringOptional
hideDefaultTierbooleanOptional
isExclusiveTierbooleanOptional
tierNamesLanguageobjectOptional
textColorstringOptional
progressBarColorstringOptional
boxBgColorstringOptional
boxTextColorstringOptional
bgCardColorstringOptional
cardOpacitynumberOptional
iconColorstringOptional
bgTypestringOptional
Responses
200Updated tier with rewards
No body
400No valid fields provided
No body
404Tier not found (TIER_NOT_FOUND)
No body
409Tier name already exists (TIER_NAME_DUPLICATE)
No body
PUT/rest_api/v2/tiers/{tierId}
PUT /rest_api/v2/tiers/{tierId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 106


{
  "name": "Diamond",
  "textColor": "#00D4FF",
  "bgCardColor": "#0D0D2B",
  "targetPointUpdate": 1500
}

Delete a tier

DELETE/rest_api/v2/tiers/{tierId}

Permanently deletes the tier and all associated rewards.

Blocked: Cannot delete the Bronze tier (systemType=bronze or targetPoint=0).

Side effects:

  • afterDeleteTier() deletes all programs with matching tierId
  • Auto-discounts (Shopify) cleaned up for privilege rewards
  • publishApp() triggered
Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
tierIdpath · stringRequired
Responses
200Tier deleted
No body
400Cannot delete Bronze tier (TIER_DELETE_BRONZE_BLOCKED)
No body
404Tier not found (TIER_NOT_FOUND)
No body
DELETE/rest_api/v2/tiers/{tierId}
DELETE /rest_api/v2/tiers/{tierId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Tier deleted
{
  "success": true,
  "data": {
    "deleted": true,
    "id": "tier123"
  }
}

Add a reward to a tier

POST/rest_api/v2/tiers/{tierId}/rewards

Creates a new reward linked to the specified tier.

Event types: amount_discount, percentage_discount, free_shipping, free_gift, bonus_point, buy_x_get_y

Key fields by event:

  • amount_discount: earnAmount, appliedTo, orderReq
  • percentage_discount: earnAmount (1-100), appliedTo, orderReq
  • free_shipping: hasLimitShipping, limitShipping
  • free_gift: specificProducts (1 item), earnAmount=100
  • bonus_point: bonusPoints (≥1)
Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
tierIdpath · stringRequired
Request body
eventstringRequired

Reward event type

titlestringRequired

Reward name

typestringOptional
earnAmountstringOptional

Discount amount/percentage. For free_gift always '100'

spendPointstringOptional

Points required to redeem

bonusPointsstringOptional

Bonus points (for bonus_point event, ≥1)

codeNamestringOptional

Code name (for privilege rewards)

appliedTostringOptional
orderReqstringOptional
orderReqAmountstringOptional
specificProductsobject[]Optional

Product list (max 1 for free_gift)

specificCollectionsstring[]Optional
combinedWithstring[]Optional
hasLimitShippingbooleanOptional
limitShippingnumberOptional
expiredAfternumberOptional
expiredUnitstringOptional
statusbooleanOptional
Responses
201Reward created
No body
404Tier not found
No body
POST/rest_api/v2/tiers/{tierId}/rewards
POST /rest_api/v2/tiers/{tierId}/rewards HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 174


{
  "event": "percentage_discount",
  "title": "10% Off",
  "type": "tier_spending",
  "earnAmount": "10",
  "spendPoint": "100",
  "appliedTo": "all",
  "orderReq": "none"
}

Update a tier reward

PUT/rest_api/v2/tiers/{tierId}/rewards/{rewardId}

Partial update of a tier reward. Only send fields to change. All fields are optional.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
tierIdpath · stringRequired
rewardIdpath · stringRequired
Request body
titlestringOptional
earnAmountstringOptional
spendPointstringOptional
bonusPointsstringOptional
codeNamestringOptional
appliedTostringOptional
orderReqstringOptional
orderReqAmountstringOptional
specificProductsobject[]Optional
combinedWithstring[]Optional
hasLimitShippingbooleanOptional
limitShippingnumberOptional
expiredAfternumberOptional
expiredUnitstringOptional
statusbooleanOptional
prioritynumberOptional
Responses
200Reward updated
No body
400No valid fields provided
No body
PUT/rest_api/v2/tiers/{tierId}/rewards/{rewardId}
PUT /rest_api/v2/tiers/{tierId}/rewards/{rewardId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 54


{
  "title": "Updated 15% Off",
  "earnAmount": "15"
}

Delete a tier reward

DELETE/rest_api/v2/tiers/{tierId}/rewards/{rewardId}

Permanently deletes the reward. If the reward is a privilege type with a Shopify auto-discount, the discount is also cleaned up.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
tierIdpath · stringRequired
rewardIdpath · stringRequired
Responses
200Reward deleted
No body
404Reward not found or not owned by shop
No body
DELETE/rest_api/v2/tiers/{tierId}/rewards/{rewardId}
DELETE /rest_api/v2/tiers/{tierId}/rewards/{rewardId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Reward deleted
{
  "success": true,
  "data": {
    "deleted": true,
    "id": "reward123"
  }
}

Get tier benefits by type

GET/rest_api/v2/tiers/benefits/{benefitType}

Retrieve tier benefits filtered by benefit type

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Parameters
benefitTypepath · stringRequired

Type of benefit to retrieve

Responses
200List of tier benefits
successbooleanOptional
Example: true
dataProgram[]Optional
Show properties
idstringOptional
Example: "prog_abc123"
titlestringOptional
Example: "Sign Up Bonus"
typestringOptional
Example: "earning"
eventstringOptional
Example: "sign_up"
statusbooleanOptional
Example: true
priorityintegerOptional
Example: 1
createdAtstring · date-timeOptional
Example: "2024-01-15T10:30:00.000Z"
updatedAtstring · date-timeOptional
Example: "2024-01-20T14:45:30.000Z"
expiredbooleanOptional
Example: false
isDraftbooleanOptional
Example: false
earnBystringOptional
Example: "price"
rateMoneynumberOptional
Example: 1
earnPointintegerOptional
Example: 100
startDatestring · date-timeOptional
Example: "2024-01-01T00:00:00.000Z"
endDatestring · date-timeOptional
Example: "2024-12-31T23:59:59.000Z"
autoRemovePointsbooleanOptional
Example: false
appliedPlaceOrderTostringOptional
Example: "all"
appliedSourcestring[]Optional
Example: ["web","pos"]
translateTitleobjectOptional
Example: {}
typeMilestonestringOptional
Example: null
milestonesobject[]Optional
Example: []
spendPointintegerOptional
Example: 500
earnAmountnumberOptional
Example: 10
redeemTypestringOptional
Example: "amount_discount"
appliedTostringOptional
Example: "all"
appliedCollectionIdsstring[]Optional
Example: []
redeemInstringOptional
Example: "available_in_online_store"
orderReqstringOptional
Example: "none"
orderReqAmountnumberOptional
Example: 0
minSpendPointstringOptional
Example: ""
maxSpendPointstringOptional
Example: ""
expiredTimestringOptional
Example: ""
userAvailabilitystringOptional
Example: "userRedeemed"
showLoyaltyPagebooleanOptional
Example: true
limitRedeemstringOptional
Example: "redeemWithoutLimit"
totalLimitationRedeemintegerOptional
Example: 0
combinedWithstring[]Optional
Example: []
specificProductsobject[]Optional
Example: []
specificProductIdsstring[]Optional
Example: []
specificCollectionsobject[]Optional
Example: []
variantIdsstring[]Optional
Example: []
freeProductIdsstring[]Optional
Example: []
giftStatusstringOptional
Example: "none"
excludeProductsobject[]Optional
Show properties
idstringOptional
titlestringOptional
imageobjectOptional
Show properties
srcstringOptional
includeProductsobject[]Optional
Show properties
idstringOptional
titlestringOptional
imageobjectOptional
Show properties
srcstringOptional
conditionsobject[]Optional
earnPointsTiersobject[]Optional
Show properties
earnPointintegerOptional
rateMoneynumberOptional
roundingMethodstringOptional
Example: "round"
skipEarnPointGuestbooleanOptional
Example: false
metaobjectOptional
Show properties
countintegerOptional

Number of items returned

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
401Authentication required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
403Plan upgrade required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
500Internal server error
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/tiers/benefits/{benefitType}
GET /rest_api/v2/tiers/benefits/{benefitType} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200List of tier benefits
{
  "success": true,
  "data": [
    {
      "id": "prog_abc123",
      "title": "Sign Up Bonus",
      "type": "earning",
      "event": "sign_up",
      "status": true,
      "priority": 1,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:30.000Z",
      "expired": false,
      "isDraft": false,
      "earnBy": "price",
      "rateMoney": 1,
      "earnPoint": 100,
      "startDate": "2024-01-01T00:00:00.000Z",
      "endDate": "2024-12-31T23:59:59.000Z",
      "autoRemovePoints": false,
      "appliedPlaceOrderTo": "all",
      "appliedSource": [
        "web",
        "pos"
      ],
      "translateTitle": {},
      "typeMilestone": null,
      "milestones": [],
      "spendPoint": 500,
      "earnAmount": 10,
      "redeemType": "amount_discount",
      "appliedTo": "all",
      "appliedCollectionIds": [],
      "redeemIn": "available_in_online_store",
      "orderReq": "none",
      "orderReqAmount": 0,
      "minSpendPoint": "",
      "maxSpendPoint": "",
      "expiredTime": "",
      "userAvailability": "userRedeemed",
      "showLoyaltyPage": true,
      "limitRedeem": "redeemWithoutLimit",
      "totalLimitationRedeem": 0,
      "combinedWith": [],
      "specificProducts": [],
      "specificProductIds": [],
      "specificCollections": [],
      "variantIds": [],
      "freeProductIds": [],
      "giftStatus": "none",
      "excludeProducts": [
        {
          "id": "string",
          "title": "string",
          "image": {
            "src": "string"
          }
        }
      ],
      "includeProducts": [
        {
          "id": "string",
          "title": "string",
          "image": {
            "src": "string"
          }
        }
      ],
      "conditions": [
        {}
      ],
      "earnPointsTiers": [
        {
          "earnPoint": 1,
          "rateMoney": 1
        }
      ],
      "roundingMethod": "round",
      "skipEarnPointGuest": false
    }
  ],
  "meta": {
    "count": 1
  },
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
RewardsReferrals
Product
Install AppWebsiteBook a Demo
Developers
JavaScript SDKREST API v2Webhook API
Company
Avada GroupHelp CenterContact
© 2026 Joy Loyalty by Avada Group. All rights reserved.