REST API v2
API references
Shop

Shop

Shop information and authentication

Get shop information

GET/rest_api/v2/whoami

Retrieve safe shop information for the authenticated shop

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Responses
200Shop information
successbooleanOptional
Example: true
dataobjectOptional
Show properties
idstringOptional
namestringOptional
domainstringOptional
emailstringOptional
planstringOptional
currencystringOptional
timezonestringOptional
countryCodestringOptional
isInstalledbooleanOptional
createdAtstring · date-timeOptional
updatedAtstring · date-timeOptional
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/whoami
GET /rest_api/v2/whoami HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Shop information
{
  "success": true,
  "data": {
    "id": "string",
    "name": "string",
    "domain": "string",
    "email": "string",
    "plan": "string",
    "currency": "string",
    "timezone": "string",
    "countryCode": "string",
    "isInstalled": true,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get shop settings

GET/rest_api/v2/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.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Responses
200Shop settings
successbooleanOptional
Example: true
dataShopSettingsOptional

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.

Show properties
primaryLanguageInAppstringOptional

Widget display language

Example: "en"
isShowSettingLanguagebooleanOptional

Show language selector in widget

Example: false
timezoneSelectedstringOptional

Shop timezone (IANA format)

Example: "America/New_York"
dateFormatstringOptional

Date display format

Example: "MM/DD/YYYY"
dateFormatForActivitystringOptional

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

Example: "HH:mm"
enabledCustomPointLabelbooleanOptional

Enable custom point label

Example: false
pointPositionstringOptional

Label position relative to point number

Example: "before"
prefixDiscountCodeGlobalstringOptional

Discount code prefix

Example: "REWARD-"
customerApplyDiscountBehaviorstringOptional

Behavior after applying discount

Example: "stay_current"
cartDrawerButtonSelectorstringOptional

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

Example: ".cart-drawer-btn"
customerFreeGiftBehaviorstringOptional

Free gift add-to-cart behavior

Example: "manual_add_to_cart"
exchangeRatePointsnumberOptional

Points-to-currency exchange rate

Example: 100
statusForReviewstringOptional

Review approval mode

Example: "approveAuto"
statusForGoogleReviewstringOptional

Google review approval mode

Example: "pending"
isSendWeeklyReportbooleanOptional

Enable weekly email report

Example: true
listBccMailWeeklyReportsstring[]Optional

BCC recipients for weekly report

Example: ["[email protected]"]
earnByOrderStatusstringOptional

When to award points for orders

Example: "financial_status"
enableLogOrderPendingFulfillbooleanOptional

Log pending fulfillment orders (only when earnByOrderStatus = fulfillment_status)

Example: false
freezeConditionsOnOrderCreatedbooleanOptional

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

Example: false
statusSyncTagOrderbooleanOptional

Enable order/customer tag sync

Example: false
orderAndCustomerTagstringOptional

Tag value for orders and customers

Example: "loyalty-member"
enableShopAppSSObooleanOptional

Enable Shop App SSO

Example: false
enableMultipassSSObooleanOptional

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

Example: false
enableGoogleSSObooleanOptional

Enable Google SSO (requires Multipass)

Example: false
enableFacebookSSObooleanOptional

Enable Facebook SSO (requires Multipass)

Example: false
allowThirdPartyAppAccessbooleanOptional

Allow third-party apps to read metafields

Example: false
autoTagEngagedMembersEnabledbooleanOptional

Enable auto-tag for engaged members

Example: false
autoTagEngagedMembersTagsstring[]Optional

Tags to apply to engaged members

Example: ["loyalty-active"]
valuePendingPointV2stringOptional

Pending points duration (positive integer as string)

Example: "7"
unitPendingPointV2stringOptional

Pending points time unit

Example: "day"
signUpLinkRedirectstring · uriOptional

Sign-up page redirect URL

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

Allow self-revoke coupon

Example: false
enableRevokeLimitbooleanOptional

Limit revoke count (requires allowRefundCoupon)

Example: false
revokeLimitIntervalstringOptional

Max revokes allowed (positive integer as string)

Example: "3"
revokeLimitUnitstringOptional

Revoke limit time unit

Example: "month"
enableRevokeTimeLimitbooleanOptional

Limit revoke time window (requires allowRefundCoupon)

Example: false
revokeTimeLimitDurationintegerOptional

Revoke window duration

Example: 7
revokeTimeLimitUnitstringOptional

Revoke window time unit

Example: "days"
enableGlobalEarningLimitbooleanOptional

Enable global earning cap

Example: false
globalEarningLimitTimeframestringOptional

Earning limit timeframe

Example: "monthly"
globalEarningLimitRollingDaysintegerOptional

Rolling window days (only when timeframe = rolling)

Example: 30
globalEarningLimitMaxPointsintegerOptional

Max points per period

Example: 5000
globalEarningLimitByTierbooleanOptional

Different limits per tier

Example: false
globalEarningLimitTiersobjectOptional

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

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

Show free product in cart

Example: false
limitShowFreeProductCartintegerOptional

Max free products displayed

Example: 3
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
401Authentication required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
GET/rest_api/v2/shop/settings
GET /rest_api/v2/shop/settings HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Accept: */*
200Shop settings
{
  "success": true,
  "data": {
    "primaryLanguageInApp": "en",
    "isShowSettingLanguage": false,
    "timezoneSelected": "America/New_York",
    "dateFormat": "MM/DD/YYYY",
    "dateFormatForActivity": "HH:mm",
    "enabledCustomPointLabel": false,
    "pointPosition": "before",
    "prefixDiscountCodeGlobal": "REWARD-",
    "customerApplyDiscountBehavior": "stay_current",
    "customerFreeGiftBehavior": "manual_add_to_cart",
    "exchangeRatePoints": 100,
    "statusForReview": "approveAuto",
    "statusForGoogleReview": "pending",
    "earnByOrderStatus": "financial_status",
    "isSendWeeklyReport": true,
    "enableGlobalEarningLimit": false,
    "isShowFreeCouponInCart": false
  },
  "meta": {},
  "timestamp": "2026-03-24T10:00:00.000Z"
}

Update shop settings

PUT/rest_api/v2/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.

Authorizations
X-Joy-Loyalty-App-KeystringRequired
X-Joy-Loyalty-Secret-KeystringRequired
Request body
primaryLanguageInAppstringOptional

Widget display language

Example: "en"
isShowSettingLanguagebooleanOptional

Show language selector in widget

Example: false
timezoneSelectedstringOptional

Shop timezone (IANA format)

Example: "America/New_York"
dateFormatstringOptional

Date display format

Example: "MM/DD/YYYY"
dateFormatForActivitystringOptional

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

Example: "HH:mm"
enabledCustomPointLabelbooleanOptional

Enable custom point label

Example: false
pointPositionstringOptional

Label position relative to point number

Example: "before"
prefixDiscountCodeGlobalstringOptional

Discount code prefix

Example: "REWARD-"
customerApplyDiscountBehaviorstringOptional

Behavior after applying discount

Example: "stay_current"
cartDrawerButtonSelectorstringOptional

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

Example: ".cart-drawer-btn"
customerFreeGiftBehaviorstringOptional

Free gift add-to-cart behavior

Example: "manual_add_to_cart"
exchangeRatePointsnumberOptional

Points-to-currency exchange rate

Example: 100
statusForReviewstringOptional

Review approval mode

Example: "approveAuto"
statusForGoogleReviewstringOptional

Google review approval mode

Example: "pending"
isSendWeeklyReportbooleanOptional

Enable weekly email report

Example: true
listBccMailWeeklyReportsstring[]Optional

BCC recipients for weekly report

Example: ["[email protected]"]
earnByOrderStatusstringOptional

When to award points for orders

Example: "financial_status"
enableLogOrderPendingFulfillbooleanOptional

Log pending fulfillment orders (only when earnByOrderStatus = fulfillment_status)

Example: false
freezeConditionsOnOrderCreatedbooleanOptional

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

Example: false
statusSyncTagOrderbooleanOptional

Enable order/customer tag sync

Example: false
orderAndCustomerTagstringOptional

Tag value for orders and customers

Example: "loyalty-member"
enableShopAppSSObooleanOptional

Enable Shop App SSO

Example: false
enableMultipassSSObooleanOptional

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

Example: false
enableGoogleSSObooleanOptional

Enable Google SSO (requires Multipass)

Example: false
enableFacebookSSObooleanOptional

Enable Facebook SSO (requires Multipass)

Example: false
allowThirdPartyAppAccessbooleanOptional

Allow third-party apps to read metafields

Example: false
autoTagEngagedMembersEnabledbooleanOptional

Enable auto-tag for engaged members

Example: false
autoTagEngagedMembersTagsstring[]Optional

Tags to apply to engaged members

Example: ["loyalty-active"]
valuePendingPointV2stringOptional

Pending points duration (positive integer as string)

Example: "7"
unitPendingPointV2stringOptional

Pending points time unit

Example: "day"
signUpLinkRedirectstring · uriOptional

Sign-up page redirect URL

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

Allow self-revoke coupon

Example: false
enableRevokeLimitbooleanOptional

Limit revoke count (requires allowRefundCoupon)

Example: false
revokeLimitIntervalstringOptional

Max revokes allowed (positive integer as string)

Example: "3"
revokeLimitUnitstringOptional

Revoke limit time unit

Example: "month"
enableRevokeTimeLimitbooleanOptional

Limit revoke time window (requires allowRefundCoupon)

Example: false
revokeTimeLimitDurationintegerOptional

Revoke window duration

Example: 7
revokeTimeLimitUnitstringOptional

Revoke window time unit

Example: "days"
enableGlobalEarningLimitbooleanOptional

Enable global earning cap

Example: false
globalEarningLimitTimeframestringOptional

Earning limit timeframe

Example: "monthly"
globalEarningLimitRollingDaysintegerOptional

Rolling window days (only when timeframe = rolling)

Example: 30
globalEarningLimitMaxPointsintegerOptional

Max points per period

Example: 5000
globalEarningLimitByTierbooleanOptional

Different limits per tier

Example: false
globalEarningLimitTiersobjectOptional

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

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

Show free product in cart

Example: false
limitShowFreeProductCartintegerOptional

Max free products displayed

Example: 3
Responses
200Settings updated successfully
successbooleanOptional
Example: true
dataShopSettingsOptional

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.

Show properties
primaryLanguageInAppstringOptional

Widget display language

Example: "en"
isShowSettingLanguagebooleanOptional

Show language selector in widget

Example: false
timezoneSelectedstringOptional

Shop timezone (IANA format)

Example: "America/New_York"
dateFormatstringOptional

Date display format

Example: "MM/DD/YYYY"
dateFormatForActivitystringOptional

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

Example: "HH:mm"
enabledCustomPointLabelbooleanOptional

Enable custom point label

Example: false
pointPositionstringOptional

Label position relative to point number

Example: "before"
prefixDiscountCodeGlobalstringOptional

Discount code prefix

Example: "REWARD-"
customerApplyDiscountBehaviorstringOptional

Behavior after applying discount

Example: "stay_current"
cartDrawerButtonSelectorstringOptional

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

Example: ".cart-drawer-btn"
customerFreeGiftBehaviorstringOptional

Free gift add-to-cart behavior

Example: "manual_add_to_cart"
exchangeRatePointsnumberOptional

Points-to-currency exchange rate

Example: 100
statusForReviewstringOptional

Review approval mode

Example: "approveAuto"
statusForGoogleReviewstringOptional

Google review approval mode

Example: "pending"
isSendWeeklyReportbooleanOptional

Enable weekly email report

Example: true
listBccMailWeeklyReportsstring[]Optional

BCC recipients for weekly report

Example: ["[email protected]"]
earnByOrderStatusstringOptional

When to award points for orders

Example: "financial_status"
enableLogOrderPendingFulfillbooleanOptional

Log pending fulfillment orders (only when earnByOrderStatus = fulfillment_status)

Example: false
freezeConditionsOnOrderCreatedbooleanOptional

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

Example: false
statusSyncTagOrderbooleanOptional

Enable order/customer tag sync

Example: false
orderAndCustomerTagstringOptional

Tag value for orders and customers

Example: "loyalty-member"
enableShopAppSSObooleanOptional

Enable Shop App SSO

Example: false
enableMultipassSSObooleanOptional

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

Example: false
enableGoogleSSObooleanOptional

Enable Google SSO (requires Multipass)

Example: false
enableFacebookSSObooleanOptional

Enable Facebook SSO (requires Multipass)

Example: false
allowThirdPartyAppAccessbooleanOptional

Allow third-party apps to read metafields

Example: false
autoTagEngagedMembersEnabledbooleanOptional

Enable auto-tag for engaged members

Example: false
autoTagEngagedMembersTagsstring[]Optional

Tags to apply to engaged members

Example: ["loyalty-active"]
valuePendingPointV2stringOptional

Pending points duration (positive integer as string)

Example: "7"
unitPendingPointV2stringOptional

Pending points time unit

Example: "day"
signUpLinkRedirectstring · uriOptional

Sign-up page redirect URL

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

Allow self-revoke coupon

Example: false
enableRevokeLimitbooleanOptional

Limit revoke count (requires allowRefundCoupon)

Example: false
revokeLimitIntervalstringOptional

Max revokes allowed (positive integer as string)

Example: "3"
revokeLimitUnitstringOptional

Revoke limit time unit

Example: "month"
enableRevokeTimeLimitbooleanOptional

Limit revoke time window (requires allowRefundCoupon)

Example: false
revokeTimeLimitDurationintegerOptional

Revoke window duration

Example: 7
revokeTimeLimitUnitstringOptional

Revoke window time unit

Example: "days"
enableGlobalEarningLimitbooleanOptional

Enable global earning cap

Example: false
globalEarningLimitTimeframestringOptional

Earning limit timeframe

Example: "monthly"
globalEarningLimitRollingDaysintegerOptional

Rolling window days (only when timeframe = rolling)

Example: 30
globalEarningLimitMaxPointsintegerOptional

Max points per period

Example: 5000
globalEarningLimitByTierbooleanOptional

Different limits per tier

Example: false
globalEarningLimitTiersobjectOptional

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

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

Show free product in cart

Example: false
limitShowFreeProductCartintegerOptional

Max free products displayed

Example: 3
metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptional
Example: "Operation completed successfully"
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
400Validation error or no valid fields provided
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
401Authentication required
successbooleanOptional
Example: false
errorobjectOptional
Show properties
messagestringOptional
Example: "Resource not found"
codestringOptional
Example: "NOT_FOUND"
statusCodeintegerOptional
Example: 404
detailsobjectOptional
timestampstring · date-timeOptional
Example: "2023-07-28T07:27:54.123Z"
PUT/rest_api/v2/shop/settings
PUT /rest_api/v2/shop/settings HTTP/1.1
Host: dev-api.joy.so
X-Joy-Loyalty-App-Key: YOUR_API_KEY
X-Joy-Loyalty-Secret-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 115


{
  "prefixDiscountCodeGlobal": "REWARD-",
  "earnByOrderStatus": "financial_status",
  "exchangeRatePoints": 100
}
200Settings updated successfully
{
  "success": true,
  "data": {
    "primaryLanguageInApp": "en",
    "isShowSettingLanguage": false,
    "timezoneSelected": "America/New_York",
    "dateFormat": "MM/DD/YYYY",
    "dateFormatForActivity": "HH:mm",
    "enabledCustomPointLabel": false,
    "pointPosition": "before",
    "prefixDiscountCodeGlobal": "REWARD-",
    "customerApplyDiscountBehavior": "stay_current",
    "cartDrawerButtonSelector": ".cart-drawer-btn",
    "customerFreeGiftBehavior": "manual_add_to_cart",
    "exchangeRatePoints": 100,
    "statusForReview": "approveAuto",
    "statusForGoogleReview": "pending",
    "isSendWeeklyReport": true,
    "listBccMailWeeklyReports": [
      "[email protected]"
    ],
    "earnByOrderStatus": "financial_status",
    "enableLogOrderPendingFulfill": false,
    "freezeConditionsOnOrderCreated": false,
    "statusSyncTagOrder": false,
    "orderAndCustomerTag": "loyalty-member",
    "enableShopAppSSO": false,
    "enableMultipassSSO": false,
    "enableGoogleSSO": false,
    "enableFacebookSSO": false,
    "allowThirdPartyAppAccess": false,
    "autoTagEngagedMembersEnabled": false,
    "autoTagEngagedMembersTags": [
      "loyalty-active"
    ],
    "valuePendingPointV2": "7",
    "unitPendingPointV2": "day",
    "signUpLinkRedirect": "https://example.com/signup",
    "allowRefundCoupon": false,
    "enableRevokeLimit": false,
    "revokeLimitInterval": "3",
    "revokeLimitUnit": "month",
    "enableRevokeTimeLimit": false,
    "revokeTimeLimitDuration": 7,
    "revokeTimeLimitUnit": "days",
    "enableGlobalEarningLimit": false,
    "globalEarningLimitTimeframe": "monthly",
    "globalEarningLimitRollingDays": 30,
    "globalEarningLimitMaxPoints": 5000,
    "globalEarningLimitByTier": false,
    "globalEarningLimitTiers": {
      "tier_abc": {
        "maxPoints": 10000,
        "unlimited": false
      }
    },
    "isShowFreeCouponInCart": false,
    "limitShowFreeProductCart": 3
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}
ReferralsBranding
Product
Install AppWebsiteBook a Demo
Developers
JavaScript SDKREST API v2Webhook API
Company
Avada GroupHelp CenterContact
© 2026 Joy Loyalty by Avada Group. All rights reserved.