# Shop
Shop information and authentication
## Get shop information
> Retrieve safe shop information for the authenticated shop
```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Shop","description":"Shop information and authentication"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"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"}}}}},"paths":{"/rest_api/v2/whoami":{"get":{"tags":["Shop"],"summary":"Get shop information","description":"Retrieve safe shop information for the authenticated shop","responses":{"200":{"description":"Shop information","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"domain":{"type":"string"},"email":{"type":"string"},"plan":{"type":"string"},"currency":{"type":"string"},"timezone":{"type":"string"},"countryCode":{"type":"string"},"isInstalled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}]}}}}}}}}}
```
## Get shop settings
> Reads all whitelisted shop settings, merged from both \`shops\` and \`settings\` Firestore collections into a single flat object.\
> \
> Only simple flag/option fields are exposed. Settings that trigger side effects (colors, metafield sync, image uploads, encryption) are managed via the admin UI only.
```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Shop","description":"Shop information and authentication"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"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"}}},"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"}}},"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"}}}}},"paths":{"/rest_api/v2/shop/settings":{"get":{"tags":["Shop"],"summary":"Get shop settings","description":"Reads all whitelisted shop settings, merged from both `shops` and `settings` Firestore collections into a single flat object.\n\nOnly simple flag/option fields are exposed. Settings that trigger side effects (colors, metafield sync, image uploads, encryption) are managed via the admin UI only.\n","operationId":"getShopSettings","responses":{"200":{"description":"Shop settings","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShopSettings"}}}]}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Update shop settings
> Partial update — send only the fields you want to change. Unknown fields are stripped by validation.\
> \
> Returns the full merged settings state after update.
```json
{"openapi":"3.0.0","info":{"title":"Joy Loyalty Program - REST API v2","version":"2.0.0"},"tags":[{"name":"Shop","description":"Shop information and authentication"}],"servers":[{"url":"https://dev-api.joy.so","description":"Staging"},{"url":"https://api.joy.so","description":"Production"}],"security":[{"JoyAuth":[],"JoySecretAuth":[]}],"components":{"securitySchemes":{"JoyAuth":{"type":"apiKey","in":"header","name":"X-Joy-Loyalty-App-Key"}},"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"}}},"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"}}},"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"}}}}},"paths":{"/rest_api/v2/shop/settings":{"put":{"tags":["Shop"],"summary":"Update shop settings","description":"Partial update — send only the fields you want to change. Unknown fields are stripped by validation.\n\nReturns the full merged settings state after update.\n","operationId":"updateShopSettings","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopSettings"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShopSettings"}}}]}}}},"400":{"description":"Validation error or no valid fields provided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```