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

200

List of tiers

application/json

successbooleanOptionalExample: true

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

401

Authentication required

application/json

403

Plan upgrade required

application/json

500

Internal server error

application/json

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: */*

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

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

cardOpacitynumber · max: 1Optional

iconColorstringOptional

bgTypestringOptional

Responses

201

Tier created

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

400

Validation error

409

Tier name already exists (TIER_NAME_DUPLICATE)

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

{
  "name": "Platinum",
  "targetPoint": 1000,
  "icon": "tier_platinum_icon",
  "textColor": "#FFFFFF",
  "bgCardColor": "#1A1A2E"
}

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

200

Tier settings

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 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: */*

200

Tier settings

{
  "success": true,
  "data": {
    "id": "text",
    "status": true,
    "entryMethod": "pointEarned",
    "milestone": "lifetime",
    "progressionType": "cumulative",
    "startDate": "text",
    "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

Body

Safe tier settings fields only. Fields requiring tier launch (entryMethod, milestone, startDate, progressionType, status) are excluded.

prefixstringOptional

isUsePrefixDiscountCodebooleanOptional

useDemotionTierbooleanOptional

typeDemotionstring · enumOptionalPossible values:

downgradeAfterstringOptional

downgradeAfterUnitstring · enumOptionalPossible values:

useResetTierbooleanOptional

resetAfterstringOptional

resetAfterUnitstring · enumOptionalPossible values:

monthResetTierstringOptional

dayResetTierstringOptional

isSyncTagsCustomerTierbooleanOptional

customerTierTagPrefixstringOptional

notificationDowngradeBeforestringOptional

notificationDowngradeBeforeUnitstring · enumOptionalPossible values:

Responses

200

Updated tier settings

No content

400

No valid fields provided

404

Tier settings not found (tiers never launched)

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

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

No content

Get tier by ID

get

/rest_api/v2/tiers/{tierId}

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Path parameters

tierIdstringRequired

Tier ID

Responses

200

Tier details

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

401

Authentication required

application/json

403

Plan upgrade required

application/json

404

Tier not found

application/json

500

Internal server error

application/json

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: */*

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

Path parameters

tierIdstringRequired

Body

All fields optional — only send fields to change

namestringOptional

targetPointUpdateintegerOptional

iconstringOptional

iconCustomstringOptional

hideDefaultTierbooleanOptional

isExclusiveTierbooleanOptional

tierNamesLanguageobjectOptional

textColorstringOptional

progressBarColorstringOptional

boxBgColorstringOptional

boxTextColorstringOptional

bgCardColorstringOptional

cardOpacitynumberOptional

iconColorstringOptional

bgTypestringOptional

Responses

200

Updated tier with rewards

No content

400

No valid fields provided

404

Tier not found (TIER_NOT_FOUND)

409

Tier name already exists (TIER_NAME_DUPLICATE)

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

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

No content

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

Path parameters

tierIdstringRequired

Responses

200

Tier deleted

application/json

400

Cannot delete Bronze tier (TIER_DELETE_BRONZE_BLOCKED)

404

Tier not found (TIER_NOT_FOUND)

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: */*

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

Path parameters

tierIdstringRequired

Body

eventstring · enumRequired

Reward event type

Possible values:

titlestringRequired

Reward name

typestring · enumOptionalDefault: tier_spendingPossible values:

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)

appliedTostring · enumOptionalPossible values:

orderReqstring · enumOptionalPossible values:

orderReqAmountstringOptional

specificProductsobject[]Optional

Product list (max 1 for free_gift)

specificCollectionsstring[]Optional

hasLimitShippingbooleanOptional

limitShippingnumberOptional

expiredAfternumberOptional

expiredUnitstring · enumOptionalPossible values:

statusbooleanOptional

Responses

201

Reward created

No content

404

Tier not found

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

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

No content

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

Path parameters

tierIdstringRequired

rewardIdstringRequired

Body

All fields optional — only send fields to change

titlestringOptional

earnAmountstringOptional

spendPointstringOptional

bonusPointsstringOptional

codeNamestringOptional

appliedTostring · enumOptionalPossible values:

orderReqstring · enumOptionalPossible values:

orderReqAmountstringOptional

specificProductsobject[]Optional

combinedWithstring[]Optional

hasLimitShippingbooleanOptional

limitShippingnumberOptional

expiredAfternumberOptional

expiredUnitstring · enumOptionalPossible values:

statusbooleanOptional

prioritynumberOptional

Responses

200

Reward updated

No content

400

No valid fields provided

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

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

No content

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

Path parameters

tierIdstringRequired

rewardIdstringRequired

Responses

200

Reward deleted

application/json

404

Reward not found or not owned by shop

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: */*

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

Path parameters

benefitTypestringRequired

Type of benefit to retrieve

Responses

200

List of tier benefits

application/json

successbooleanOptionalExample: true

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

401

Authentication required

application/json

403

Plan upgrade required

application/json

500

Internal server error

application/json

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: */*

{
  "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": "text",
          "title": "text",
          "image": {
            "src": "text"
          }
        }
      ],
      "includeProducts": [
        {
          "id": "text",
          "title": "text",
          "image": {
            "src": "text"
          }
        }
      ],
      "conditions": [
        {}
      ],
      "earnPointsTiers": [
        {
          "earnPoint": 1,
          "rateMoney": 1
        }
      ],
      "roundingMethod": "round",
      "skipEarnPointGuest": false
    }
  ],
  "meta": {
    "count": 1
  },
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

PreviousRewards NextReferrals

Last updated 3 months ago