REST API v2
API references
Models

Models

SuccessResponse

successbooleanOptional
Example: true
dataobjectOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"

ErrorResponse

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"

PaginatedResponse

successbooleanOptional
Example: true
dataobject[]Required

Array of items for current page

metaobjectOptional

Pagination metadata container

Show properties
paginationobjectOptional
Show properties
hasNextbooleanRequired

True if more results exist after current page

hasPrebooleanRequired

True if results exist before current page

totalintegerOptional

Total count of all matching results (when available)

totalPageintegerOptional

Total number of pages calculated as ceil(total/limit) (when available)

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"

ListResponse

successbooleanOptional
Example: true
dataobject[]Optional
metaobjectOptional
Show properties
countintegerOptional

Number of items returned

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"

ShopSettings

Shop configuration settings. Only simple flag/option fields are exposed. Settings with side effects (colors, metafield sync, image upload, encryption) are managed via admin UI only.

primaryLanguageInAppstringOptional

Widget display language

Example: "en"
isShowSettingLanguagebooleanOptional

Show language selector in widget

Example: false
timezoneSelectedstringOptional

Shop timezone (IANA format)

Example: "America/New_York"
dateFormatstringOptional

Date display format

Example: "MM/DD/YYYY"
dateFormatForActivitystringOptional

Time format for activity log (24h or 12h)

Example: "HH:mm"
enabledCustomPointLabelbooleanOptional

Enable custom point label

Example: false
pointPositionstringOptional

Label position relative to point number

Example: "before"
prefixDiscountCodeGlobalstringOptional

Discount code prefix

Example: "REWARD-"
customerApplyDiscountBehaviorstringOptional

Behavior after applying discount

Example: "stay_current"
cartDrawerButtonSelectorstringOptional

CSS selector for cart drawer button (required when behavior = open_cart_drawer)

Example: ".cart-drawer-btn"
customerFreeGiftBehaviorstringOptional

Free gift add-to-cart behavior

Example: "manual_add_to_cart"
exchangeRatePointsnumberOptional

Points-to-currency exchange rate

Example: 100
statusForReviewstringOptional

Review approval mode

Example: "approveAuto"
statusForGoogleReviewstringOptional

Google review approval mode

Example: "pending"
isSendWeeklyReportbooleanOptional

Enable weekly email report

Example: true
listBccMailWeeklyReportsstring[]Optional

BCC recipients for weekly report

Example: ["[email protected]"]
earnByOrderStatusstringOptional

When to award points for orders

Example: "financial_status"
enableLogOrderPendingFulfillbooleanOptional

Log pending fulfillment orders (only when earnByOrderStatus = fulfillment_status)

Example: false
freezeConditionsOnOrderCreatedbooleanOptional

Freeze conditions at order creation (only when earnByOrderStatus = fulfillment_status)

Example: false
statusSyncTagOrderbooleanOptional

Enable order/customer tag sync

Example: false
orderAndCustomerTagstringOptional

Tag value for orders and customers

Example: "loyalty-member"
enableShopAppSSObooleanOptional

Enable Shop App SSO

Example: false
enableMultipassSSObooleanOptional

Enable Multipass SSO (flag only, set secret via admin UI)

Example: false
enableGoogleSSObooleanOptional

Enable Google SSO (requires Multipass)

Example: false
enableFacebookSSObooleanOptional

Enable Facebook SSO (requires Multipass)

Example: false
allowThirdPartyAppAccessbooleanOptional

Allow third-party apps to read metafields

Example: false
autoTagEngagedMembersEnabledbooleanOptional

Enable auto-tag for engaged members

Example: false
autoTagEngagedMembersTagsstring[]Optional

Tags to apply to engaged members

Example: ["loyalty-active"]
valuePendingPointV2stringOptional

Pending points duration (positive integer as string)

Example: "7"
unitPendingPointV2stringOptional

Pending points time unit

Example: "day"
signUpLinkRedirectstring · uriOptional

Sign-up page redirect URL

Example: "https://example.com/signup"
allowRefundCouponbooleanOptional

Allow self-revoke coupon

Example: false
enableRevokeLimitbooleanOptional

Limit revoke count (requires allowRefundCoupon)

Example: false
revokeLimitIntervalstringOptional

Max revokes allowed (positive integer as string)

Example: "3"
revokeLimitUnitstringOptional

Revoke limit time unit

Example: "month"
enableRevokeTimeLimitbooleanOptional

Limit revoke time window (requires allowRefundCoupon)

Example: false
revokeTimeLimitDurationintegerOptional

Revoke window duration

Example: 7
revokeTimeLimitUnitstringOptional

Revoke window time unit

Example: "days"
enableGlobalEarningLimitbooleanOptional

Enable global earning cap

Example: false
globalEarningLimitTimeframestringOptional

Earning limit timeframe

Example: "monthly"
globalEarningLimitRollingDaysintegerOptional

Rolling window days (only when timeframe = rolling)

Example: 30
globalEarningLimitMaxPointsintegerOptional

Max points per period

Example: 5000
globalEarningLimitByTierbooleanOptional

Different limits per tier

Example: false
globalEarningLimitTiersobjectOptional

Per-tier limit overrides. Format: { [tierId]: { maxPoints: number, unlimited: boolean } }

Example: {"tier_abc":{"maxPoints":10000,"unlimited":false}}
isShowFreeCouponInCartbooleanOptional

Show free product in cart

Example: false
limitShowFreeProductCartintegerOptional

Max free products displayed

Example: 3

WidgetBranding

Widget branding configuration (branding_point_v2). Maps to admin Storefront → Branding → Widget Design (4 tabs merged into flat object).

primaryColorstringOptional

Primary widget color (hex)

Example: "#25272C"
secondaryColorstringOptional

Secondary widget color (hex)

Example: "#2F3136"
textColorstringOptional

Text color (hex)

Example: "#FFFFFF"
backgroundColorstringOptional

Background color (hex)

iconColorstringOptional

Icon color (hex)

buttonTextColorstringOptional

Button text color (hex)

Example: "#FFFFFF"
buttonBgColorstringOptional

Button background color (hex)

Example: "#25272C"
cornerRadiusnumberOptional

Corner radius in pixels

Example: 8
widgetIconstringOptional

Widget launcher icon

Example: "popup_crown"
widgetLabelstringOptional

Widget launcher label text

Example: "Rewards"
bannerTypestringOptional

Banner display type

Example: "default"
useMinimalButtonsbooleanOptional

Use minimal button style in widget

Example: true
floatBtnPositionstringOptional

Float button position on screen

Example: "left-bottom"
floatButtonLauncherstringOptional

Float button launcher style

Example: "icon_and_label"
floatBtnColorstringOptional

Float button color (hex)

Example: "#25272C"
floatBtnTextColorstringOptional

Float button text color (hex)

Example: "#FFFFFF"
themeTextFontstringOptional

Theme text font family

Example: "Inter"
headingTextFontstringOptional

Heading font family

Example: "Inter"
hideOnMobilebooleanOptional

Hide widget on mobile devices

Example: false
hideOnDesktopbooleanOptional

Hide widget on desktop

hideFloatBtnbooleanOptional

Hide the floating button entirely

Example: false
showOnlyLoggedInbooleanOptional

Show widget only to logged-in users

Example: false
autoShowPopupbooleanOptional

Auto-show popup when page loads

Example: false
showLowestTierFirstbooleanOptional

Show lowest VIP tier first in widget

Example: true
widgetPositionstringOptional

Widget popup position on screen

Example: "left-bottom"

ReferralBranding

Referral popup branding configuration. Maps to admin Storefront → Branding → Referral.

brandColorstringOptional

Primary referral color (hex)

Example: "#6366F1"
textColorstringOptional

Text color (hex)

Example: "#FFFFFF"
actionBgColorstringOptional

Action button background color (hex)

actionTextColorstringOptional

Action button text color (hex)

colorTypestringOptional

Color mode

Example: "template"
customSolidColorstringOptional

Custom solid color (hex)

themeTextFontstringOptional

Font family

Example: "Inter"
typeShowPopupstringOptional

Popup display type

isAutoClosePopUpbooleanOptional

Auto-close popup after delay

closingPopUpTimenumberOptional

Auto-close delay in seconds

Example: 10
frequencyShowPopupstringOptional

Display frequency

isShowSubscribeNewsletterbooleanOptional

Show newsletter subscribe checkbox

ReminderBranding

Proactive reminder branding configuration. Maps to admin Storefront → Branding → Reminder.

showUnusedDiscountbooleanOptional

Show unused discount reminder

unusedDiscountHeadingstringOptional

Unused discount heading text

unusedDiscountButtonstringOptional

Unused discount button text

showRewardRedemptionbooleanOptional

Show reward redemption reminder

rewardRedemptionHeadingstringOptional

Reward redemption heading text

rewardRedemptionButtonstringOptional

Reward redemption button text

showMilestoneAchievedbooleanOptional

Show milestone achieved reminder

milestoneAchievedHeadingstringOptional

Milestone heading text

autoCloseAfternumberOptional

Auto-close delay in seconds

Example: 10
floatBtnPositionstringOptional

Reminder button position

reminderPrioritystring[]Optional

Reminder display order

BrandingOverview

All branding types combined for quick overview scan.

widgetWidgetBrandingOptional

Widget branding configuration (branding_point_v2). Maps to admin Storefront → Branding → Widget Design (4 tabs merged into flat object).

Show properties
primaryColorstringOptional

Primary widget color (hex)

Example: "#25272C"
secondaryColorstringOptional

Secondary widget color (hex)

Example: "#2F3136"
textColorstringOptional

Text color (hex)

Example: "#FFFFFF"
backgroundColorstringOptional

Background color (hex)

iconColorstringOptional

Icon color (hex)

buttonTextColorstringOptional

Button text color (hex)

Example: "#FFFFFF"
buttonBgColorstringOptional

Button background color (hex)

Example: "#25272C"
cornerRadiusnumberOptional

Corner radius in pixels

Example: 8
widgetIconstringOptional

Widget launcher icon

Example: "popup_crown"
widgetLabelstringOptional

Widget launcher label text

Example: "Rewards"
bannerTypestringOptional

Banner display type

Example: "default"
useMinimalButtonsbooleanOptional

Use minimal button style in widget

Example: true
floatBtnPositionstringOptional

Float button position on screen

Example: "left-bottom"
floatButtonLauncherstringOptional

Float button launcher style

Example: "icon_and_label"
floatBtnColorstringOptional

Float button color (hex)

Example: "#25272C"
floatBtnTextColorstringOptional

Float button text color (hex)

Example: "#FFFFFF"
themeTextFontstringOptional

Theme text font family

Example: "Inter"
headingTextFontstringOptional

Heading font family

Example: "Inter"
hideOnMobilebooleanOptional

Hide widget on mobile devices

Example: false
hideOnDesktopbooleanOptional

Hide widget on desktop

hideFloatBtnbooleanOptional

Hide the floating button entirely

Example: false
showOnlyLoggedInbooleanOptional

Show widget only to logged-in users

Example: false
autoShowPopupbooleanOptional

Auto-show popup when page loads

Example: false
showLowestTierFirstbooleanOptional

Show lowest VIP tier first in widget

Example: true
widgetPositionstringOptional

Widget popup position on screen

Example: "left-bottom"
referralReferralBrandingOptional

Referral popup branding configuration. Maps to admin Storefront → Branding → Referral.

Show properties
brandColorstringOptional

Primary referral color (hex)

Example: "#6366F1"
textColorstringOptional

Text color (hex)

Example: "#FFFFFF"
actionBgColorstringOptional

Action button background color (hex)

actionTextColorstringOptional

Action button text color (hex)

colorTypestringOptional

Color mode

Example: "template"
customSolidColorstringOptional

Custom solid color (hex)

themeTextFontstringOptional

Font family

Example: "Inter"
typeShowPopupstringOptional

Popup display type

isAutoClosePopUpbooleanOptional

Auto-close popup after delay

closingPopUpTimenumberOptional

Auto-close delay in seconds

Example: 10
frequencyShowPopupstringOptional

Display frequency

isShowSubscribeNewsletterbooleanOptional

Show newsletter subscribe checkbox

reminderReminderBrandingOptional

Proactive reminder branding configuration. Maps to admin Storefront → Branding → Reminder.

Show properties
showUnusedDiscountbooleanOptional

Show unused discount reminder

unusedDiscountHeadingstringOptional

Unused discount heading text

unusedDiscountButtonstringOptional

Unused discount button text

showRewardRedemptionbooleanOptional

Show reward redemption reminder

rewardRedemptionHeadingstringOptional

Reward redemption heading text

rewardRedemptionButtonstringOptional

Reward redemption button text

showMilestoneAchievedbooleanOptional

Show milestone achieved reminder

milestoneAchievedHeadingstringOptional

Milestone heading text

autoCloseAfternumberOptional

Auto-close delay in seconds

Example: 10
floatBtnPositionstringOptional

Reminder button position

reminderPrioritystring[]Optional

Reminder display order

TranslationConfig

Full translation object containing config and text for all languages. Language keys (en, fr, de...) are dynamic objects with translation key-value pairs. Mirrors the internal admin translation system.

primaryLanguagestringOptional

Primary language code

Example: "en"
detectMethodstringOptional

How to detect customer language:

  • customerIp: By IP geolocation
  • browserLanguage: By browser language setting
  • optionalStorefrontLanguage: Use Shopify storefront language
Example: "browserLanguage"
additionalLanguagesobject[]Optional

Additional languages with active status

Show properties
codestringOptional

Language code

Example: "fr"
activebooleanOptional

Whether language is active for customers

Example: true
embedContentstring[]Optional

Languages for embedded content (FAQs, exclusive products)

Example: ["en","fr"]

AddLanguageRequest

primaryLanguagestringRequired

Source language code to translate from

Example: "en"
additionalLanguagestringRequired

Target language code to add

Example: "fr"

FaqTranslationsUpdate

translateFaqsobjectRequired

FAQ translations keyed by language code

Example: {"en":[{"title":"How does it work?","content":"Earn points on every purchase...","orderBy":0}],"fr":[{"title":"Comment ça marche?","content":"Gagnez des points à chaque achat...","orderBy":0}]}

Program

Loyalty program (earning or spending) with all fields that may be returned by the API. Note: Actual responses may only include non-null fields due to automatic filtering.

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

Customer

idstringOptional

Internal customer ID

Example: "b1wvKrxdDZ11U8tUlyyx"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
namestringOptional

Customer full name

Example: "John Doe"
firstNamestringOptional

Customer first name

Example: "John"
lastNamestringOptional

Customer last name

Example: "Doe"
typestringOptional

Customer type

Example: "member"
pointintegerOptional

Current available points

Example: 100
tierPointintegerOptional

Points used for tier calculation

Example: 100
pendingPointintegerOptional

Points pending approval

Example: 0
totalSpentnumberOptional

Total amount spent

Example: 0
totalEarnedPointsintegerOptional

Lifetime earned points

Example: 100
hasPointbooleanOptional

Whether customer has available points

Example: true
hasJoinedProgrambooleanOptional

Whether customer joined loyalty program

Example: true
orderCountintegerOptional

Number of orders placed

Example: 0
statestringOptional

Account state

Example: "enabled"
latestActivitystring · date-timeOptional

Last activity timestamp

Example: "2025-04-29T10:23:05.990Z"
notificationsobjectOptional

Customer notification preferences

Example: {}
acceptsMarketingbooleanOptional

Marketing consent

Example: false
birthdaystringOptional

Birthday in MM/DD format

Example: "05/15"
dateOfBirthstring · dateOptional

Date of birth in YYYY-MM-DD format

Example: "1990-05-15"
tierIdstringOptional

Current tier ID

Example: "1Fe1kqHZbE7Alx1GmFEC"
tierNamestringOptional

Current tier name

Example: "Bronze"
tierUpdatedAtstring · date-timeOptional

Last tier update timestamp

Example: "2025-06-16T10:20:58.636Z"
phonestringOptional

Phone number

Example: null
pointsRemainintegerOptional

Points needed for next tier

Example: 4900
birthMonthstringOptional

Birth month in MM format

Example: "05"
isCustomerB2BbooleanOptional

Whether customer is B2B

Example: false
earnSignUpbooleanOptional

Whether customer earned signup points

Example: true
referralCodestringOptional

Customer's referral code

Example: "2kxRoqlDQMp"
hasTierbooleanOptional

Whether customer has a tier assigned

Example: false
totalSpentCurrencyCodestringOptional

Currency code for spending

Example: "VND"
createdAtstring · date-timeOptional

Account creation timestamp

Example: "2025-04-29T10:23:05.991Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-16T10:20:58.663Z"

Activity

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

idstringOptional

Activity ID

Example: "act_abc123"
shopIdstringOptional

Shop ID

Example: "shop_xyz789"
customerIdstringOptional

Internal customer ID

Example: "cust_def456"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7801029525739
emailstring · emailOptional

Customer email address

Example: "[email protected]"
contentstringOptional

Activity description/content

Example: "Award points via REST API"
typestringOptional

Activity type

Example: "earnPoint"
sourcestringOptional

Source of the activity

Example: "rest_api"
eventstringOptional

Program event that triggered this activity

Example: "earn_point_rest_api"
oldPointintegerOptional

Previous point balance

Example: 50
newPointintegerOptional

New point balance after this activity

Example: 150
programIdstringOptional

Associated program ID

Example: "prog_abc123"
programTitlestringOptional

Associated program title

Example: "Manual Point Award"
priceRuleIdstringOptional

Shopify price rule ID for discounts

Example: null
discountIdstringOptional

Shopify discount ID

Example: null
couponCodestringOptional

Generated coupon code

Example: null
orderIdstringOptional

Associated Shopify order ID

Example: null
orderNamestringOptional

Shopify order name

Example: null
orderNumberintegerOptional

Shopify order number

Example: null
orderCurrencystringOptional

Order currency code

Example: null
earnBystringOptional

How points were earned (price/order)

Example: null
rateMoneynumberOptional

Money to points conversion rate

Example: null
earnPointintegerOptional

Points earned in this activity

Example: 100
spendPointintegerOptional

Points spent in this activity

Example: null
referralCustomerEmailstringOptional

Email of referring customer

Example: null
referredCustomerEmailstringOptional

Email of referred customer

Example: null
milestoneOrderintegerOptional

Milestone order number

Example: null
isPendingPointPlaceOrderbooleanOptional

Whether points are pending for order

Example: null
refundPendingPointintegerOptional

Refunded pending points

Example: null
pendingPointUntilstring · date-timeOptional

When pending points expire

Example: null
adminNotestringOptional

Admin note for this activity

Example: null
userNotestringOptional

User note for this activity

Example: null
reasonstringOptional

Reason for the activity

Example: null
createdAtstring · date-timeOptional

Activity creation timestamp

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

Last update timestamp

Example: "2024-01-15T10:30:00.000Z"

Reward

idstringOptional

Reward ID

Example: "OPfV7dXaPn1Ejbm9piPs"
customerIdstringOptional

Internal customer ID

Example: "o9AQeUCXYDjbeFm7vAKy"
emailstring · emailOptional

Customer email address

Example: "[email protected]"
couponCodestringOptional

Generated coupon/discount code

Example: "JOY-8PBFA801B2FH"
programTitlestringOptional

Program title

Example: "Points for discounts"
shopifyCustomerIdintegerOptional

Shopify customer ID

Example: 7603687882987
programDescriptionstringOptional

Program description

Example: "1 x 1% discount"
orderReqAmountstringOptional

Minimum order amount required

Example: "$1"
expiredAtstring · date-timeOptional

Reward expiration date

Example: null
discountStatusstringOptional

Current discount status

Example: "active"
programobjectOptional
Show properties
idstringOptional

Program ID

Example: "akwQ96WZJMIqrG26PNlC"
titlestringOptional

Program title

Example: "Points for discounts"
createdAtstring · date-timeOptional

Reward creation timestamp

Example: "2025-06-12T10:31:25.781Z"
updatedAtstring · date-timeOptional

Last update timestamp

Example: "2025-06-12T10:31:25.781Z"

Tier

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.

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"

TierReward

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"

TierCreate

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

TierUpdate

All fields optional — only send fields to change

namestringOptional
targetPointUpdateintegerOptional
iconstringOptional
iconCustomstringOptional
hideDefaultTierbooleanOptional
isExclusiveTierbooleanOptional
tierNamesLanguageobjectOptional
textColorstringOptional
progressBarColorstringOptional
boxBgColorstringOptional
boxTextColorstringOptional
bgCardColorstringOptional
cardOpacitynumberOptional
iconColorstringOptional
bgTypestringOptional

TierSettings

Global VIP tier program settings

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

TierSettingsUpdate

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

prefixstringOptional
isUsePrefixDiscountCodebooleanOptional
useDemotionTierbooleanOptional
typeDemotionstringOptional
downgradeAfterstringOptional
downgradeAfterUnitstringOptional
useResetTierbooleanOptional
resetAfterstringOptional
resetAfterUnitstringOptional
monthResetTierstringOptional
dayResetTierstringOptional
isSyncTagsCustomerTierbooleanOptional
customerTierTagPrefixstringOptional
notificationDowngradeBeforestringOptional
notificationDowngradeBeforeUnitstringOptional

TierRewardCreate

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

TierRewardUpdate

All fields optional — only send fields to change

titlestringOptional
earnAmountstringOptional
spendPointstringOptional
bonusPointsstringOptional
codeNamestringOptional
appliedTostringOptional
orderReqstringOptional
orderReqAmountstringOptional
specificProductsobject[]Optional
combinedWithstring[]Optional
hasLimitShippingbooleanOptional
limitShippingnumberOptional
expiredAfternumberOptional
expiredUnitstringOptional
statusbooleanOptional
prioritynumberOptional

Shop

Shop information with safe fields returned by the whoami endpoint

idstringOptional

Shop ID

Example: "shop_abc123"
namestringOptional

Shop name

Example: "My Awesome Store"
domainstringOptional

Shop domain

Example: "my-store.myshopify.com"
emailstring · emailOptional

Shop owner email

Example: "[email protected]"
planstringOptional

Current subscription plan

Example: "professional"
currencystringOptional

Shop currency code

Example: "USD"
timezonestringOptional

Shop timezone

Example: "America/New_York"
countryCodestringOptional

Shop country code

Example: "US"
isInstalledbooleanOptional

Whether the Joy app is installed

Example: true
createdAtstring · date-timeOptional

Shop creation timestamp

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

Last update timestamp

Example: "2024-01-20T14:45:30.000Z"
TranslationsOverview
Product
Install AppWebsiteBook a Demo
Developers
JavaScript SDKREST API v2Webhook API
Company
Avada GroupHelp CenterContact
© 2026 Joy Loyalty by Avada Group. All rights reserved.