Tiers

Tier management

Get all tiers

get

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/tiers

Retrieve all customer tiers for the authenticated shop

Header parameters

X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}

X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}

Responses

200

List of tiers

application/json

401

Authentication required

application/json

403

Plan upgrade required

application/json

500

Internal server error

application/json

get

/rest_api/v2/tiers

HTTPcURLJavaScriptPython

GET /rest_api/v2/tiers HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
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"
    }
  ]
}

Get tier by ID

get

https://dev-api.joy.sohttps://api.joy.so

/rest_api/v2/tiers/{tierId}

Path parameters

tierIdstringRequired

Tier ID

Header parameters

X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}

X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}

Responses

200

Tier details

application/json

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}

HTTPcURLJavaScriptPython

GET /rest_api/v2/tiers/{tierId} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
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"
  }
}

Get tier benefits by type

get

https://dev-api.joy.sohttps://api.joy.so

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

Retrieve tier benefits filtered by benefit type

Path parameters

benefitTypestringRequired

Type of benefit to retrieve

Header parameters

X-Joy-Loyalty-App-KeystringRequired

App ID of your shop which retrieved from the Settings page

Example: {{appKey}}

X-Joy-Loyalty-Secret-KeystringRequired

Secret Key of your shop which retrieved from the Settings page

Example: {{secretKey}}

Responses

200

List of tier benefits

application/json

401

Authentication required

application/json

403

Plan upgrade required

application/json

500

Internal server error

application/json

get

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

HTTPcURLJavaScriptPython

GET /rest_api/v2/tiers/benefits/{benefitType} HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: text
X-Joy-Loyalty-Secret-Key: text
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"
}