# Models

## The SuccessResponse object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}
```

## The ErrorResponse object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"},"details":{"type":"object"}}},"timestamp":{"type":"string","format":"date-time"}}}}}}
```

## The PaginatedResponse object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"PaginatedResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"type":"object"},"description":"Array of items for current page"},"meta":{"type":"object","properties":{"pagination":{"type":"object","required":["hasNext","hasPre"],"properties":{"hasNext":{"type":"boolean","description":"True if more results exist after current page"},"hasPre":{"type":"boolean","description":"True if results exist before current page"},"total":{"type":"integer","description":"Total count of all matching results (when available)"},"totalPage":{"type":"integer","description":"Total number of pages calculated as ceil(total/limit) (when available)"}}}},"description":"Pagination metadata container"}}}]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}
```

## The ListResponse object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"ListResponse":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"count":{"type":"integer","description":"Number of items returned"}}}}}]},"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"meta":{"type":"object","description":"Additional metadata such as counts and pagination"},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}
```

## The ShopSettings object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"ShopSettings":{"type":"object","description":"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.","properties":{"primaryLanguageInApp":{"type":"string","enum":["en","en-US","fr","es","de","it","ja","id","zh-CN"],"description":"Widget display language"},"isShowSettingLanguage":{"type":"boolean","description":"Show language selector in widget"},"timezoneSelected":{"type":"string","description":"Shop timezone (IANA format)"},"dateFormat":{"type":"string","enum":["MM/DD/YYYY","DD/MM/YYYY","YYYY/MM/DD"],"description":"Date display format"},"dateFormatForActivity":{"type":"string","enum":["HH:mm","hh:mm A"],"description":"Time format for activity log (24h or 12h)"},"enabledCustomPointLabel":{"type":"boolean","description":"Enable custom point label"},"pointPosition":{"type":"string","enum":["before","after"],"description":"Label position relative to point number"},"prefixDiscountCodeGlobal":{"type":"string","description":"Discount code prefix"},"customerApplyDiscountBehavior":{"type":"string","enum":["stay_current","go_to_cart","open_cart_drawer"],"description":"Behavior after applying discount"},"cartDrawerButtonSelector":{"type":"string","description":"CSS selector for cart drawer button (required when behavior = open_cart_drawer)"},"customerFreeGiftBehavior":{"type":"string","enum":["manual_add_to_cart","auto_add_to_cart"],"description":"Free gift add-to-cart behavior"},"exchangeRatePoints":{"type":"number","description":"Points-to-currency exchange rate"},"statusForReview":{"type":"string","enum":["pending","approveAuto"],"description":"Review approval mode"},"statusForGoogleReview":{"type":"string","enum":["pending","approveAuto"],"description":"Google review approval mode"},"isSendWeeklyReport":{"type":"boolean","description":"Enable weekly email report"},"listBccMailWeeklyReports":{"type":"array","items":{"type":"string","format":"email"},"description":"BCC recipients for weekly report"},"earnByOrderStatus":{"type":"string","enum":["financial_status","fulfillment_status"],"description":"When to award points for orders"},"enableLogOrderPendingFulfill":{"type":"boolean","description":"Log pending fulfillment orders (only when earnByOrderStatus = fulfillment_status)"},"freezeConditionsOnOrderCreated":{"type":"boolean","description":"Freeze conditions at order creation (only when earnByOrderStatus = fulfillment_status)"},"statusSyncTagOrder":{"type":"boolean","description":"Enable order/customer tag sync"},"orderAndCustomerTag":{"type":"string","description":"Tag value for orders and customers"},"enableShopAppSSO":{"type":"boolean","description":"Enable Shop App SSO"},"enableMultipassSSO":{"type":"boolean","description":"Enable Multipass SSO (flag only, set secret via admin UI)"},"enableGoogleSSO":{"type":"boolean","description":"Enable Google SSO (requires Multipass)"},"enableFacebookSSO":{"type":"boolean","description":"Enable Facebook SSO (requires Multipass)"},"allowThirdPartyAppAccess":{"type":"boolean","description":"Allow third-party apps to read metafields"},"autoTagEngagedMembersEnabled":{"type":"boolean","description":"Enable auto-tag for engaged members"},"autoTagEngagedMembersTags":{"type":"array","items":{"type":"string"},"description":"Tags to apply to engaged members"},"valuePendingPointV2":{"type":"string","description":"Pending points duration (positive integer as string)"},"unitPendingPointV2":{"type":"string","enum":["minute","day","month"],"description":"Pending points time unit"},"signUpLinkRedirect":{"type":"string","format":"uri","description":"Sign-up page redirect URL"},"allowRefundCoupon":{"type":"boolean","description":"Allow self-revoke coupon"},"enableRevokeLimit":{"type":"boolean","description":"Limit revoke count (requires allowRefundCoupon)"},"revokeLimitInterval":{"type":"string","description":"Max revokes allowed (positive integer as string)"},"revokeLimitUnit":{"type":"string","enum":["minute","hour","day","week","month","year","lifetime"],"description":"Revoke limit time unit"},"enableRevokeTimeLimit":{"type":"boolean","description":"Limit revoke time window (requires allowRefundCoupon)"},"revokeTimeLimitDuration":{"type":"integer","description":"Revoke window duration"},"revokeTimeLimitUnit":{"type":"string","enum":["minutes","hours","days","weeks","months","years"],"description":"Revoke window time unit"},"enableGlobalEarningLimit":{"type":"boolean","description":"Enable global earning cap"},"globalEarningLimitTimeframe":{"type":"string","enum":["yearly","monthly","rolling"],"description":"Earning limit timeframe"},"globalEarningLimitRollingDays":{"type":"integer","minimum":1,"maximum":365,"description":"Rolling window days (only when timeframe = rolling)"},"globalEarningLimitMaxPoints":{"type":"integer","description":"Max points per period"},"globalEarningLimitByTier":{"type":"boolean","description":"Different limits per tier"},"globalEarningLimitTiers":{"type":"object","description":"Per-tier limit overrides. Format: { [tierId]: { maxPoints: number, unlimited: boolean } }"},"isShowFreeCouponInCart":{"type":"boolean","description":"Show free product in cart"},"limitShowFreeProductCart":{"type":"integer","description":"Max free products displayed"}}}}}}
```

## The WidgetBranding object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"WidgetBranding":{"type":"object","description":"Widget branding configuration (branding_point_v2). Maps to admin Storefront → Branding → Widget Design (4 tabs merged into flat object).","properties":{"primaryColor":{"type":"string","description":"Primary widget color (hex)"},"secondaryColor":{"type":"string","description":"Secondary widget color (hex)"},"textColor":{"type":"string","description":"Text color (hex)"},"backgroundColor":{"type":"string","description":"Background color (hex)"},"iconColor":{"type":"string","description":"Icon color (hex)"},"buttonTextColor":{"type":"string","description":"Button text color (hex)"},"buttonBgColor":{"type":"string","description":"Button background color (hex)"},"cornerRadius":{"type":"number","description":"Corner radius in pixels"},"widgetIcon":{"type":"string","enum":["crown","default","popup_gift","popup_star","popup_reward","popup_crown","shopping-bag","piggy-bank","ribbon","heart","custom","blank"],"description":"Widget launcher icon"},"widgetLabel":{"type":"string","description":"Widget launcher label text"},"bannerType":{"type":"string","enum":["default","custom","image","blank"],"description":"Banner display type"},"useMinimalButtons":{"type":"boolean","description":"Use minimal button style in widget"},"floatBtnPosition":{"type":"string","enum":["left-bottom","right-bottom"],"description":"Float button position on screen"},"floatButtonLauncher":{"type":"string","enum":["icon_only","label_only","icon_and_label","point_balance"],"description":"Float button launcher style"},"floatBtnColor":{"type":"string","description":"Float button color (hex)"},"floatBtnTextColor":{"type":"string","description":"Float button text color (hex)"},"themeTextFont":{"type":"string","description":"Theme text font family"},"headingTextFont":{"type":"string","description":"Heading font family"},"hideOnMobile":{"type":"boolean","description":"Hide widget on mobile devices"},"hideOnDesktop":{"type":"boolean","description":"Hide widget on desktop"},"hideFloatBtn":{"type":"boolean","description":"Hide the floating button entirely"},"showOnlyLoggedIn":{"type":"boolean","description":"Show widget only to logged-in users"},"autoShowPopup":{"type":"boolean","description":"Auto-show popup when page loads"},"showLowestTierFirst":{"type":"boolean","description":"Show lowest VIP tier first in widget"},"widgetPosition":{"type":"string","enum":["left-bottom","right-bottom"],"description":"Widget popup position on screen"}}}}}}
```

## The ReferralBranding object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"ReferralBranding":{"type":"object","description":"Referral popup branding configuration. Maps to admin Storefront → Branding → Referral.","properties":{"brandColor":{"type":"string","description":"Primary referral color (hex)"},"textColor":{"type":"string","description":"Text color (hex)"},"actionBgColor":{"type":"string","description":"Action button background color (hex)"},"actionTextColor":{"type":"string","description":"Action button text color (hex)"},"colorType":{"type":"string","enum":["template","custom-solid","custom-gradient"],"description":"Color mode"},"customSolidColor":{"type":"string","description":"Custom solid color (hex)"},"themeTextFont":{"type":"string","description":"Font family"},"typeShowPopup":{"type":"string","description":"Popup display type"},"isAutoClosePopUp":{"type":"boolean","description":"Auto-close popup after delay"},"closingPopUpTime":{"type":"number","description":"Auto-close delay in seconds"},"frequencyShowPopup":{"type":"string","description":"Display frequency"},"isShowSubscribeNewsletter":{"type":"boolean","description":"Show newsletter subscribe checkbox"}}}}}}
```

## The ReminderBranding object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"ReminderBranding":{"type":"object","description":"Proactive reminder branding configuration. Maps to admin Storefront → Branding → Reminder.","properties":{"showUnusedDiscount":{"type":"boolean","description":"Show unused discount reminder"},"unusedDiscountHeading":{"type":"string","description":"Unused discount heading text"},"unusedDiscountButton":{"type":"string","description":"Unused discount button text"},"showRewardRedemption":{"type":"boolean","description":"Show reward redemption reminder"},"rewardRedemptionHeading":{"type":"string","description":"Reward redemption heading text"},"rewardRedemptionButton":{"type":"string","description":"Reward redemption button text"},"showMilestoneAchieved":{"type":"boolean","description":"Show milestone achieved reminder"},"milestoneAchievedHeading":{"type":"string","description":"Milestone heading text"},"autoCloseAfter":{"type":"number","description":"Auto-close delay in seconds"},"floatBtnPosition":{"type":"string","enum":["left-bottom","right-bottom"],"description":"Reminder button position"},"reminderPriority":{"type":"array","items":{"type":"string"},"description":"Reminder display order"}}}}}}
```

## The BrandingOverview object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"BrandingOverview":{"type":"object","description":"All branding types combined for quick overview scan.","properties":{"widget":{"$ref":"#/components/schemas/WidgetBranding"},"referral":{"$ref":"#/components/schemas/ReferralBranding"},"reminder":{"$ref":"#/components/schemas/ReminderBranding"}}},"WidgetBranding":{"type":"object","description":"Widget branding configuration (branding_point_v2). Maps to admin Storefront → Branding → Widget Design (4 tabs merged into flat object).","properties":{"primaryColor":{"type":"string","description":"Primary widget color (hex)"},"secondaryColor":{"type":"string","description":"Secondary widget color (hex)"},"textColor":{"type":"string","description":"Text color (hex)"},"backgroundColor":{"type":"string","description":"Background color (hex)"},"iconColor":{"type":"string","description":"Icon color (hex)"},"buttonTextColor":{"type":"string","description":"Button text color (hex)"},"buttonBgColor":{"type":"string","description":"Button background color (hex)"},"cornerRadius":{"type":"number","description":"Corner radius in pixels"},"widgetIcon":{"type":"string","enum":["crown","default","popup_gift","popup_star","popup_reward","popup_crown","shopping-bag","piggy-bank","ribbon","heart","custom","blank"],"description":"Widget launcher icon"},"widgetLabel":{"type":"string","description":"Widget launcher label text"},"bannerType":{"type":"string","enum":["default","custom","image","blank"],"description":"Banner display type"},"useMinimalButtons":{"type":"boolean","description":"Use minimal button style in widget"},"floatBtnPosition":{"type":"string","enum":["left-bottom","right-bottom"],"description":"Float button position on screen"},"floatButtonLauncher":{"type":"string","enum":["icon_only","label_only","icon_and_label","point_balance"],"description":"Float button launcher style"},"floatBtnColor":{"type":"string","description":"Float button color (hex)"},"floatBtnTextColor":{"type":"string","description":"Float button text color (hex)"},"themeTextFont":{"type":"string","description":"Theme text font family"},"headingTextFont":{"type":"string","description":"Heading font family"},"hideOnMobile":{"type":"boolean","description":"Hide widget on mobile devices"},"hideOnDesktop":{"type":"boolean","description":"Hide widget on desktop"},"hideFloatBtn":{"type":"boolean","description":"Hide the floating button entirely"},"showOnlyLoggedIn":{"type":"boolean","description":"Show widget only to logged-in users"},"autoShowPopup":{"type":"boolean","description":"Auto-show popup when page loads"},"showLowestTierFirst":{"type":"boolean","description":"Show lowest VIP tier first in widget"},"widgetPosition":{"type":"string","enum":["left-bottom","right-bottom"],"description":"Widget popup position on screen"}}},"ReferralBranding":{"type":"object","description":"Referral popup branding configuration. Maps to admin Storefront → Branding → Referral.","properties":{"brandColor":{"type":"string","description":"Primary referral color (hex)"},"textColor":{"type":"string","description":"Text color (hex)"},"actionBgColor":{"type":"string","description":"Action button background color (hex)"},"actionTextColor":{"type":"string","description":"Action button text color (hex)"},"colorType":{"type":"string","enum":["template","custom-solid","custom-gradient"],"description":"Color mode"},"customSolidColor":{"type":"string","description":"Custom solid color (hex)"},"themeTextFont":{"type":"string","description":"Font family"},"typeShowPopup":{"type":"string","description":"Popup display type"},"isAutoClosePopUp":{"type":"boolean","description":"Auto-close popup after delay"},"closingPopUpTime":{"type":"number","description":"Auto-close delay in seconds"},"frequencyShowPopup":{"type":"string","description":"Display frequency"},"isShowSubscribeNewsletter":{"type":"boolean","description":"Show newsletter subscribe checkbox"}}},"ReminderBranding":{"type":"object","description":"Proactive reminder branding configuration. Maps to admin Storefront → Branding → Reminder.","properties":{"showUnusedDiscount":{"type":"boolean","description":"Show unused discount reminder"},"unusedDiscountHeading":{"type":"string","description":"Unused discount heading text"},"unusedDiscountButton":{"type":"string","description":"Unused discount button text"},"showRewardRedemption":{"type":"boolean","description":"Show reward redemption reminder"},"rewardRedemptionHeading":{"type":"string","description":"Reward redemption heading text"},"rewardRedemptionButton":{"type":"string","description":"Reward redemption button text"},"showMilestoneAchieved":{"type":"boolean","description":"Show milestone achieved reminder"},"milestoneAchievedHeading":{"type":"string","description":"Milestone heading text"},"autoCloseAfter":{"type":"number","description":"Auto-close delay in seconds"},"floatBtnPosition":{"type":"string","enum":["left-bottom","right-bottom"],"description":"Reminder button position"},"reminderPriority":{"type":"array","items":{"type":"string"},"description":"Reminder display order"}}}}}}
```

## The TranslationConfig object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TranslationConfig":{"type":"object","description":"Full translation object containing config and text for all languages.\nLanguage keys (en, fr, de...) are dynamic objects with translation key-value pairs.\nMirrors the internal admin translation system.\n","properties":{"primaryLanguage":{"type":"string","description":"Primary language code"},"detectMethod":{"type":"string","enum":["customerIp","browserLanguage","optionalStorefrontLanguage"],"description":"How to detect customer language:\n- customerIp: By IP geolocation\n- browserLanguage: By browser language setting\n- optionalStorefrontLanguage: Use Shopify storefront language\n"},"additionalLanguages":{"type":"array","description":"Additional languages with active status","items":{"type":"object","properties":{"code":{"type":"string","description":"Language code"},"active":{"type":"boolean","description":"Whether language is active for customers"}}}},"embedContent":{"type":"array","description":"Languages for embedded content (FAQs, exclusive products)","items":{"type":"string"}}},"additionalProperties":{"type":"object","description":"Dynamic language keys (en, fr, de, etc.) containing translation key-value pairs.\nEach language object has ~300+ keys mapping English source text to translated text.\n","additionalProperties":{"type":"string"}}}}}}
```

## The AddLanguageRequest object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"AddLanguageRequest":{"type":"object","required":["primaryLanguage","additionalLanguage"],"properties":{"primaryLanguage":{"type":"string","description":"Source language code to translate from"},"additionalLanguage":{"type":"string","description":"Target language code to add"}}}}}}
```

## The FaqTranslationsUpdate object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"FaqTranslationsUpdate":{"type":"object","required":["translateFaqs"],"properties":{"translateFaqs":{"type":"object","description":"FAQ translations keyed by language code","additionalProperties":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"FAQ question"},"content":{"type":"string","description":"FAQ answer"},"orderBy":{"type":"number","description":"Display order"}}}}}}}}}}
```

## The Program object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"Program":{"type":"object","description":"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.","properties":{"id":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","enum":["earning","spending","tier_spending","tier"]},"event":{"type":"string"},"status":{"type":"boolean"},"priority":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expired":{"type":"boolean"},"isDraft":{"type":"boolean"},"earnBy":{"type":"string","enum":["price","order"]},"rateMoney":{"type":"number"},"earnPoint":{"type":"integer"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"autoRemovePoints":{"type":"boolean"},"appliedPlaceOrderTo":{"type":"string","enum":["all","vip-tier"]},"appliedSource":{"type":"array","items":{"type":"string"}},"translateTitle":{"type":"object"},"typeMilestone":{"type":"string"},"milestones":{"type":"array","items":{"type":"object"}},"spendPoint":{"type":"integer"},"earnAmount":{"type":"number"},"redeemType":{"type":"string"},"appliedTo":{"type":"string"},"appliedCollectionIds":{"type":"array","items":{"type":"string"}},"redeemIn":{"type":"string","enum":["available_in_pos","available_in_online_store"]},"orderReq":{"type":"string","enum":["none","min_amount"]},"orderReqAmount":{"type":"number"},"minSpendPoint":{"type":"string"},"maxSpendPoint":{"type":"string"},"expiredTime":{"type":"string"},"userAvailability":{"type":"string","enum":["allUsers","userRedeemed"]},"showLoyaltyPage":{"type":"boolean"},"limitRedeem":{"type":"string","enum":["redeemWithoutLimit","redeemLimit"]},"totalLimitationRedeem":{"type":"integer"},"combinedWith":{"type":"array","items":{"type":"string"}},"specificProducts":{"type":"array","items":{"type":"object"}},"specificProductIds":{"type":"array","items":{"type":"string"}},"specificCollections":{"type":"array","items":{"type":"object"}},"variantIds":{"type":"array","items":{"type":"string"}},"freeProductIds":{"type":"array","items":{"type":"string"}},"giftStatus":{"type":"string","enum":["none","hot","expiring-soon"]},"excludeProducts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"image":{"type":"object","properties":{"src":{"type":"string"}}}}}},"includeProducts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"image":{"type":"object","properties":{"src":{"type":"string"}}}}}},"conditions":{"type":"array","items":{"type":"object"}},"earnPointsTiers":{"type":"array","items":{"type":"object","properties":{"earnPoint":{"type":"integer"},"rateMoney":{"type":"number"}}}},"roundingMethod":{"type":"string","enum":["round","floor","ceil"]},"skipEarnPointGuest":{"type":"boolean"}}}}}}
```

## The Customer object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"Customer":{"type":"object","properties":{"id":{"type":"string","description":"Internal customer ID"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"name":{"type":"string","description":"Customer full name"},"firstName":{"type":"string","description":"Customer first name"},"lastName":{"type":"string","description":"Customer last name"},"type":{"type":"string","enum":["member","guest","left"],"description":"Customer type"},"point":{"type":"integer","description":"Current available points"},"tierPoint":{"type":"integer","description":"Points used for tier calculation"},"pendingPoint":{"type":"integer","description":"Points pending approval"},"totalSpent":{"type":"number","description":"Total amount spent"},"totalEarnedPoints":{"type":"integer","description":"Lifetime earned points"},"hasPoint":{"type":"boolean","description":"Whether customer has available points"},"hasJoinedProgram":{"type":"boolean","description":"Whether customer joined loyalty program"},"orderCount":{"type":"integer","description":"Number of orders placed"},"state":{"type":"string","enum":["enabled","disabled"],"description":"Account state"},"latestActivity":{"type":"string","format":"date-time","description":"Last activity timestamp"},"notifications":{"type":"object","description":"Customer notification preferences"},"acceptsMarketing":{"type":"boolean","description":"Marketing consent"},"birthday":{"type":"string","description":"Birthday in MM/DD format"},"dateOfBirth":{"type":"string","format":"date","description":"Date of birth in YYYY-MM-DD format"},"tierId":{"type":"string","description":"Current tier ID"},"tierName":{"type":"string","description":"Current tier name"},"tierUpdatedAt":{"type":"string","format":"date-time","description":"Last tier update timestamp"},"phone":{"type":"string","nullable":true,"description":"Phone number"},"pointsRemain":{"type":"integer","description":"Points needed for next tier"},"birthMonth":{"type":"string","description":"Birth month in MM format"},"isCustomerB2B":{"type":"boolean","description":"Whether customer is B2B"},"earnSignUp":{"type":"boolean","description":"Whether customer earned signup points"},"referralCode":{"type":"string","description":"Customer's referral code"},"hasTier":{"type":"boolean","description":"Whether customer has a tier assigned"},"totalSpentCurrencyCode":{"type":"string","description":"Currency code for spending"},"createdAt":{"type":"string","format":"date-time","description":"Account creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}
```

## The Activity object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"Activity":{"type":"object","description":"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.","properties":{"id":{"type":"string","description":"Activity ID"},"shopId":{"type":"string","description":"Shop ID"},"customerId":{"type":"string","description":"Internal customer ID"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"content":{"type":"string","description":"Activity description/content"},"type":{"type":"string","description":"Activity type"},"source":{"type":"string","description":"Source of the activity"},"event":{"type":"string","description":"Program event that triggered this activity"},"oldPoint":{"type":"integer","description":"Previous point balance"},"newPoint":{"type":"integer","description":"New point balance after this activity"},"programId":{"type":"string","nullable":true,"description":"Associated program ID"},"programTitle":{"type":"string","nullable":true,"description":"Associated program title"},"priceRuleId":{"type":"string","nullable":true,"description":"Shopify price rule ID for discounts"},"discountId":{"type":"string","nullable":true,"description":"Shopify discount ID"},"couponCode":{"type":"string","nullable":true,"description":"Generated coupon code"},"orderId":{"type":"string","nullable":true,"description":"Associated Shopify order ID"},"orderName":{"type":"string","nullable":true,"description":"Shopify order name"},"orderNumber":{"type":"integer","nullable":true,"description":"Shopify order number"},"orderCurrency":{"type":"string","nullable":true,"description":"Order currency code"},"earnBy":{"type":"string","nullable":true,"description":"How points were earned (price/order)"},"rateMoney":{"type":"number","nullable":true,"description":"Money to points conversion rate"},"earnPoint":{"type":"integer","nullable":true,"description":"Points earned in this activity"},"spendPoint":{"type":"integer","nullable":true,"description":"Points spent in this activity"},"referralCustomerEmail":{"type":"string","nullable":true,"description":"Email of referring customer"},"referredCustomerEmail":{"type":"string","nullable":true,"description":"Email of referred customer"},"milestoneOrder":{"type":"integer","nullable":true,"description":"Milestone order number"},"isPendingPointPlaceOrder":{"type":"boolean","nullable":true,"description":"Whether points are pending for order"},"refundPendingPoint":{"type":"integer","nullable":true,"description":"Refunded pending points"},"pendingPointUntil":{"type":"string","format":"date-time","nullable":true,"description":"When pending points expire"},"adminNote":{"type":"string","nullable":true,"description":"Admin note for this activity"},"userNote":{"type":"string","nullable":true,"description":"User note for this activity"},"reason":{"type":"string","nullable":true,"description":"Reason for the activity"},"createdAt":{"type":"string","format":"date-time","description":"Activity creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}
```

## The Reward object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"Reward":{"type":"object","properties":{"id":{"type":"string","description":"Reward ID"},"customerId":{"type":"string","description":"Internal customer ID"},"email":{"type":"string","format":"email","description":"Customer email address"},"couponCode":{"type":"string","description":"Generated coupon/discount code"},"programTitle":{"type":"string","description":"Program title"},"shopifyCustomerId":{"type":"integer","description":"Shopify customer ID"},"programDescription":{"type":"string","description":"Program description"},"orderReqAmount":{"type":"string","description":"Minimum order amount required"},"expiredAt":{"type":"string","format":"date-time","nullable":true,"description":"Reward expiration date"},"discountStatus":{"type":"string","enum":["active","used","expired"],"description":"Current discount status"},"program":{"type":"object","nullable":true,"properties":{"id":{"type":"string","description":"Program ID"},"title":{"type":"string","description":"Program title"}}},"createdAt":{"type":"string","format":"date-time","description":"Reward creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}
```

## The Tier object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"Tier":{"type":"object","description":"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.","properties":{"id":{"type":"string","description":"Tier ID"},"name":{"type":"string","description":"Tier name"},"icon":{"type":"string","description":"Default icon URL"},"iconCustom":{"type":"string","description":"Custom icon URL"},"targetPoint":{"type":"integer","description":"Points required to reach this tier"},"targetPointUpdate":{"type":"integer","description":"Updated points required"},"members":{"type":"integer","description":"Number of customers in this tier"},"placedOrderReward":{"type":"boolean","description":"Whether tier has place order rewards"},"rateMoney":{"type":"number","description":"Money rate for earning points"},"earnPoint":{"type":"integer","description":"Points earning configuration"},"shopId":{"type":"string","description":"Shop ID"},"imageBlock":{"type":"string","description":"Image block URL"},"tierRewards":{"type":"array","description":"Tier-specific rewards/benefits","items":{"$ref":"#/components/schemas/TierReward"}},"inactive":{"type":"boolean","description":"Whether tier is inactive"},"isExclusiveTier":{"type":"boolean","description":"Whether tier is exclusive"},"prevNames":{"type":"array","description":"Previous names of this tier","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time","description":"Tier creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}},"TierReward":{"type":"object","properties":{"id":{"type":"string","description":"Reward ID"},"status":{"type":"boolean","description":"Whether reward is active"},"title":{"type":"string","description":"Reward title"},"redeemType":{"type":"string","enum":["fixed","dynamic"],"description":"Type of redemption"},"spendPoint":{"type":"integer","description":"Points required to redeem"},"minSpendPoint":{"type":"string","description":"Minimum points to spend"},"maxSpendPoint":{"type":"string","description":"Maximum points to spend"},"appliedTo":{"type":"string","enum":["all","specific","sf_product"],"description":"Where reward applies"},"orderReq":{"type":"string","enum":["none","min_amount"],"description":"Order requirements"},"orderReqAmount":{"type":"number","description":"Minimum order amount required"},"expiredAfter":{"type":"string","description":"When reward expires"},"expiredTime":{"type":"string","format":"date-time","nullable":true,"description":"Specific expiration time"},"type":{"type":"string","description":"Reward type"},"codeName":{"type":"string","description":"Code name for reward"},"earnAmount":{"type":"string","description":"Amount earned"},"event":{"type":"string","description":"Event type for reward"},"bonusPoints":{"type":"string","description":"Bonus points awarded"},"priority":{"type":"integer","description":"Reward priority"},"showLoyaltyPage":{"type":"boolean","description":"Whether to show on loyalty page"},"translateTitle":{"type":"object","description":"Translated titles for different languages"},"expired":{"type":"boolean","description":"Whether reward has expired"},"createdAt":{"type":"string","format":"date-time","description":"Reward creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}
```

## The TierReward object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierReward":{"type":"object","properties":{"id":{"type":"string","description":"Reward ID"},"status":{"type":"boolean","description":"Whether reward is active"},"title":{"type":"string","description":"Reward title"},"redeemType":{"type":"string","enum":["fixed","dynamic"],"description":"Type of redemption"},"spendPoint":{"type":"integer","description":"Points required to redeem"},"minSpendPoint":{"type":"string","description":"Minimum points to spend"},"maxSpendPoint":{"type":"string","description":"Maximum points to spend"},"appliedTo":{"type":"string","enum":["all","specific","sf_product"],"description":"Where reward applies"},"orderReq":{"type":"string","enum":["none","min_amount"],"description":"Order requirements"},"orderReqAmount":{"type":"number","description":"Minimum order amount required"},"expiredAfter":{"type":"string","description":"When reward expires"},"expiredTime":{"type":"string","format":"date-time","nullable":true,"description":"Specific expiration time"},"type":{"type":"string","description":"Reward type"},"codeName":{"type":"string","description":"Code name for reward"},"earnAmount":{"type":"string","description":"Amount earned"},"event":{"type":"string","description":"Event type for reward"},"bonusPoints":{"type":"string","description":"Bonus points awarded"},"priority":{"type":"integer","description":"Reward priority"},"showLoyaltyPage":{"type":"boolean","description":"Whether to show on loyalty page"},"translateTitle":{"type":"object","description":"Translated titles for different languages"},"expired":{"type":"boolean","description":"Whether reward has expired"},"createdAt":{"type":"string","format":"date-time","description":"Reward creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}
```

## The TierCreate object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierCreate":{"type":"object","required":["name","targetPoint"],"properties":{"name":{"type":"string","description":"Tier name (must be unique)"},"targetPoint":{"type":"integer","minimum":0,"description":"Points required to reach this tier"},"targetPointUpdate":{"type":"integer","description":"Defaults to targetPoint if not provided"},"icon":{"type":"string","description":"Icon ID (tier_bronze_icon, tier_sliver_icon, tier_gold_icon, tier_diamond_icon, tier_platinum_icon, tier_crown_icon)"},"iconCustom":{"type":"string","description":"Custom icon URL"},"hideDefaultTier":{"type":"boolean"},"isExclusiveTier":{"type":"boolean"},"tierNamesLanguage":{"type":"object","description":"Multi-language tier names {locale: name}"},"textColor":{"type":"string","description":"Hex color"},"progressBarColor":{"type":"string"},"boxBgColor":{"type":"string"},"boxTextColor":{"type":"string"},"bgCardColor":{"type":"string"},"cardOpacity":{"type":"number","minimum":0,"maximum":1},"iconColor":{"type":"string"},"bgType":{"type":"string"},"rewards":{"type":"array","description":"Inline rewards to create with the tier","items":{"$ref":"#/components/schemas/TierRewardCreate"}}}},"TierRewardCreate":{"type":"object","required":["event","title"],"properties":{"event":{"type":"string","enum":["amount_discount","percentage_discount","free_shipping","free_gift","bonus_point","buy_x_get_y"],"description":"Reward event type"},"title":{"type":"string","description":"Reward name"},"type":{"type":"string","enum":["tier_spending","tier_privileges","pre_tier_reward"],"default":"tier_spending"},"earnAmount":{"type":"string","description":"Discount amount/percentage. For free_gift always '100'"},"spendPoint":{"type":"string","description":"Points required to redeem"},"bonusPoints":{"type":"string","description":"Bonus points (for bonus_point event, ≥1)"},"codeName":{"type":"string","description":"Code name (for privilege rewards)"},"appliedTo":{"type":"string","enum":["all","specific_product","specific"]},"orderReq":{"type":"string","enum":["none","min_amount","min_quantity"]},"orderReqAmount":{"type":"string"},"specificProducts":{"type":"array","description":"Product list (max 1 for free_gift)","items":{"type":"object"}},"specificCollections":{"type":"array","items":{"type":"string"}},"combinedWith":{"type":"array","items":{"type":"string","enum":["orderDiscounts","shippingDiscounts","productDiscounts"]}},"hasLimitShipping":{"type":"boolean"},"limitShipping":{"type":"number"},"expiredAfter":{"type":"number"},"expiredUnit":{"type":"string","enum":["day","month"]},"status":{"type":"boolean"}}}}}}
```

## The TierUpdate object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierUpdate":{"type":"object","description":"All fields optional — only send fields to change","properties":{"name":{"type":"string"},"targetPointUpdate":{"type":"integer","minimum":0},"icon":{"type":"string"},"iconCustom":{"type":"string"},"hideDefaultTier":{"type":"boolean"},"isExclusiveTier":{"type":"boolean"},"tierNamesLanguage":{"type":"object"},"textColor":{"type":"string"},"progressBarColor":{"type":"string"},"boxBgColor":{"type":"string"},"boxTextColor":{"type":"string"},"bgCardColor":{"type":"string"},"cardOpacity":{"type":"number"},"iconColor":{"type":"string"},"bgType":{"type":"string"}}}}}}
```

## The TierSettings object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierSettings":{"type":"object","description":"Global VIP tier program settings","properties":{"id":{"type":"string","readOnly":true},"status":{"type":"boolean","description":"Tier program active (read-only via API, requires launch)"},"entryMethod":{"type":"string","enum":["pointEarned","moneySpent","numberOfOrders"],"description":"How customers qualify for tiers (read-only via API)"},"milestone":{"type":"string","enum":["lifetime","halfyear","specificDay"],"description":"Reset cycle (read-only via API)"},"progressionType":{"type":"string","enum":["cumulative","reset"],"description":"Points progression type (read-only via API)"},"startDate":{"type":"string","description":"Program start date (read-only via API)"},"prefix":{"type":"string","description":"Discount code prefix"},"isUsePrefixDiscountCode":{"type":"boolean"},"useDemotionTier":{"type":"boolean","description":"Enable tier demotion"},"typeDemotion":{"type":"string","enum":["downgrade_tier","reset_tier"]},"downgradeAfter":{"type":"string","description":"Duration before downgrade"},"downgradeAfterUnit":{"type":"string","enum":["day","month","year"]},"useResetTier":{"type":"boolean"},"monthResetTier":{"type":"string"},"dayResetTier":{"type":"string"},"isSyncTagsCustomerTier":{"type":"boolean","description":"Auto-tag customers in Shopify by tier"},"customerTierTagPrefix":{"type":"string"},"notificationDowngradeBefore":{"type":"string"},"notificationDowngradeBeforeUnit":{"type":"string","enum":["day","month"]}}}}}}
```

## The TierSettingsUpdate object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierSettingsUpdate":{"type":"object","description":"Safe tier settings fields only. Fields requiring tier launch\n(entryMethod, milestone, startDate, progressionType, status) are excluded.\n","properties":{"prefix":{"type":"string"},"isUsePrefixDiscountCode":{"type":"boolean"},"useDemotionTier":{"type":"boolean"},"typeDemotion":{"type":"string","enum":["downgrade_tier","reset_tier"]},"downgradeAfter":{"type":"string"},"downgradeAfterUnit":{"type":"string","enum":["day","month","year"]},"useResetTier":{"type":"boolean"},"resetAfter":{"type":"string"},"resetAfterUnit":{"type":"string","enum":["day","month","year"]},"monthResetTier":{"type":"string"},"dayResetTier":{"type":"string"},"isSyncTagsCustomerTier":{"type":"boolean"},"customerTierTagPrefix":{"type":"string"},"notificationDowngradeBefore":{"type":"string"},"notificationDowngradeBeforeUnit":{"type":"string","enum":["day","month"]}}}}}}
```

## The TierRewardCreate object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierRewardCreate":{"type":"object","required":["event","title"],"properties":{"event":{"type":"string","enum":["amount_discount","percentage_discount","free_shipping","free_gift","bonus_point","buy_x_get_y"],"description":"Reward event type"},"title":{"type":"string","description":"Reward name"},"type":{"type":"string","enum":["tier_spending","tier_privileges","pre_tier_reward"],"default":"tier_spending"},"earnAmount":{"type":"string","description":"Discount amount/percentage. For free_gift always '100'"},"spendPoint":{"type":"string","description":"Points required to redeem"},"bonusPoints":{"type":"string","description":"Bonus points (for bonus_point event, ≥1)"},"codeName":{"type":"string","description":"Code name (for privilege rewards)"},"appliedTo":{"type":"string","enum":["all","specific_product","specific"]},"orderReq":{"type":"string","enum":["none","min_amount","min_quantity"]},"orderReqAmount":{"type":"string"},"specificProducts":{"type":"array","description":"Product list (max 1 for free_gift)","items":{"type":"object"}},"specificCollections":{"type":"array","items":{"type":"string"}},"combinedWith":{"type":"array","items":{"type":"string","enum":["orderDiscounts","shippingDiscounts","productDiscounts"]}},"hasLimitShipping":{"type":"boolean"},"limitShipping":{"type":"number"},"expiredAfter":{"type":"number"},"expiredUnit":{"type":"string","enum":["day","month"]},"status":{"type":"boolean"}}}}}}
```

## The TierRewardUpdate object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"TierRewardUpdate":{"type":"object","description":"All fields optional — only send fields to change","properties":{"title":{"type":"string"},"earnAmount":{"type":"string"},"spendPoint":{"type":"string"},"bonusPoints":{"type":"string"},"codeName":{"type":"string"},"appliedTo":{"type":"string","enum":["all","specific_product","specific"]},"orderReq":{"type":"string","enum":["none","min_amount","min_quantity"]},"orderReqAmount":{"type":"string"},"specificProducts":{"type":"array","items":{"type":"object"}},"combinedWith":{"type":"array","items":{"type":"string"}},"hasLimitShipping":{"type":"boolean"},"limitShipping":{"type":"number"},"expiredAfter":{"type":"number"},"expiredUnit":{"type":"string","enum":["day","month"]},"status":{"type":"boolean"},"priority":{"type":"number"}}}}}}
```

## The Shop object

```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"components":{"schemas":{"Shop":{"type":"object","description":"Shop information with safe fields returned by the whoami endpoint","properties":{"id":{"type":"string","description":"Shop ID"},"name":{"type":"string","description":"Shop name"},"domain":{"type":"string","description":"Shop domain"},"email":{"type":"string","format":"email","description":"Shop owner email"},"plan":{"type":"string","description":"Current subscription plan"},"currency":{"type":"string","description":"Shop currency code"},"timezone":{"type":"string","description":"Shop timezone"},"countryCode":{"type":"string","description":"Shop country code"},"isInstalled":{"type":"boolean","description":"Whether the Joy app is installed"},"createdAt":{"type":"string","format":"date-time","description":"Shop creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}}}}}}
```