> For the complete documentation index, see [llms.txt](https://devdocs.joy.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devdocs.joy.so/joy-rest-api-v2/api-references/models.md). # 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"}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://devdocs.joy.so/joy-rest-api-v2/api-references/models.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.