Branding

Widget, referral, and reminder branding configuration

Get branding overview

get

/rest_api/v2/shop/branding

Returns all 3 branding types (widget, referral, reminder) in a single response. Useful for scanning the full branding configuration before making changes.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200

All branding configurations

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

get/rest_api/v2/shop/branding

GET /rest_api/v2/shop/branding 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: */*

200

All branding configurations

{
  "success": true,
  "data": {
    "widget": {
      "primaryColor": "#25272C",
      "widgetPosition": "left-bottom",
      "widgetIcon": "popup_crown",
      "floatButtonLauncher": "icon_and_label",
      "hideOnMobile": false
    },
    "referral": {
      "brandColor": "#6366F1",
      "colorType": "template"
    },
    "reminder": {
      "showUnusedDiscount": true,
      "autoCloseAfter": 10
    }
  },
  "meta": {},
  "timestamp": "2026-03-24T10:00:00.000Z"
}

get

/rest_api/v2/shop/branding/widget

Reads widget branding configuration (branding_point_v2). Maps to admin Storefront → Branding → Widget Design.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200

Widget branding configuration

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

get/rest_api/v2/shop/branding/widget

GET /rest_api/v2/shop/branding/widget 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: */*

200

Widget branding configuration

{
  "success": true,
  "data": {
    "primaryColor": "#25272C",
    "secondaryColor": "#2F3136",
    "textColor": "#FFFFFF",
    "backgroundColor": "text",
    "iconColor": "text",
    "buttonTextColor": "#FFFFFF",
    "buttonBgColor": "#25272C",
    "cornerRadius": 8,
    "widgetIcon": "popup_crown",
    "widgetLabel": "Rewards",
    "bannerType": "default",
    "useMinimalButtons": true,
    "floatBtnPosition": "left-bottom",
    "floatButtonLauncher": "icon_and_label",
    "floatBtnColor": "#25272C",
    "floatBtnTextColor": "#FFFFFF",
    "themeTextFont": "Inter",
    "headingTextFont": "Inter",
    "hideOnMobile": false,
    "hideOnDesktop": true,
    "hideFloatBtn": false,
    "showOnlyLoggedIn": false,
    "autoShowPopup": false,
    "showLowestTierFirst": true,
    "widgetPosition": "left-bottom"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

put

/rest_api/v2/shop/branding/widget

Partial update — send only fields to change. Triggers metafield sync. Returns full widget branding state after update.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Body

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

primaryColorstringOptional

Primary widget color (hex)

Example: #25272C

secondaryColorstringOptional

Secondary widget color (hex)

Example: #2F3136

textColorstringOptional

Text color (hex)

Example: #FFFFFF

backgroundColorstringOptional

Background color (hex)

iconColorstringOptional

Icon color (hex)

buttonTextColorstringOptional

Button text color (hex)

Example: #FFFFFF

buttonBgColorstringOptional

Button background color (hex)

Example: #25272C

cornerRadiusnumberOptional

Corner radius in pixels

Example: 8

widgetIconstring · enumOptional

Widget launcher icon

Example: popup_crownPossible values:

widgetLabelstringOptional

Widget launcher label text

Example: Rewards

bannerTypestring · enumOptional

Banner display type

Example: defaultPossible values:

useMinimalButtonsbooleanOptional

Use minimal button style in widget

Example: true

floatBtnPositionstring · enumOptional

Float button position on screen

Example: left-bottomPossible values:

floatButtonLauncherstring · enumOptional

Float button launcher style

Example: icon_and_labelPossible values:

floatBtnColorstringOptional

Float button color (hex)

Example: #25272C

floatBtnTextColorstringOptional

Float button text color (hex)

Example: #FFFFFF

themeTextFontstringOptional

Theme text font family

Example: Inter

headingTextFontstringOptional

Heading font family

Example: Inter

hideOnMobilebooleanOptional

Hide widget on mobile devices

Example: false

hideOnDesktopbooleanOptional

Hide widget on desktop

hideFloatBtnbooleanOptional

Hide the floating button entirely

Example: false

showOnlyLoggedInbooleanOptional

Show widget only to logged-in users

Example: false

autoShowPopupbooleanOptional

Auto-show popup when page loads

Example: false

showLowestTierFirstbooleanOptional

Show lowest VIP tier first in widget

Example: true

widgetPositionstring · enumOptional

Widget popup position on screen

Example: left-bottomPossible values:

Responses

200

Widget branding updated

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

400

Validation error or no valid fields

application/json

put/rest_api/v2/shop/branding/widget

PUT /rest_api/v2/shop/branding/widget 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: 102

{
  "primaryColor": "#FF6B35",
  "buttonBgColor": "#FF6B35",
  "widgetPosition": "right-bottom",
  "cornerRadius": 12
}

{
  "success": true,
  "data": {
    "primaryColor": "#25272C",
    "secondaryColor": "#2F3136",
    "textColor": "#FFFFFF",
    "backgroundColor": "text",
    "iconColor": "text",
    "buttonTextColor": "#FFFFFF",
    "buttonBgColor": "#25272C",
    "cornerRadius": 8,
    "widgetIcon": "popup_crown",
    "widgetLabel": "Rewards",
    "bannerType": "default",
    "useMinimalButtons": true,
    "floatBtnPosition": "left-bottom",
    "floatButtonLauncher": "icon_and_label",
    "floatBtnColor": "#25272C",
    "floatBtnTextColor": "#FFFFFF",
    "themeTextFont": "Inter",
    "headingTextFont": "Inter",
    "hideOnMobile": false,
    "hideOnDesktop": true,
    "hideFloatBtn": false,
    "showOnlyLoggedIn": false,
    "autoShowPopup": false,
    "showLowestTierFirst": true,
    "widgetPosition": "left-bottom"
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get referral branding

get

/rest_api/v2/shop/branding/referral

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

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200

Referral branding configuration

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

get/rest_api/v2/shop/branding/referral

GET /rest_api/v2/shop/branding/referral 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: */*

200

Referral branding configuration

{
  "success": true,
  "data": {
    "brandColor": "#6366F1",
    "textColor": "#FFFFFF",
    "actionBgColor": "text",
    "actionTextColor": "text",
    "colorType": "template",
    "customSolidColor": "text",
    "themeTextFont": "Inter",
    "typeShowPopup": "text",
    "isAutoClosePopUp": true,
    "closingPopUpTime": 10,
    "frequencyShowPopup": "text",
    "isShowSubscribeNewsletter": true
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update referral branding

put

/rest_api/v2/shop/branding/referral

Partial update for referral popup branding. Triggers metafield sync.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Body

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

brandColorstringOptional

Primary referral color (hex)

Example: #6366F1

textColorstringOptional

Text color (hex)

Example: #FFFFFF

actionBgColorstringOptional

Action button background color (hex)

actionTextColorstringOptional

Action button text color (hex)

colorTypestring · enumOptional

Color mode

Example: templatePossible values:

customSolidColorstringOptional

Custom solid color (hex)

themeTextFontstringOptional

Font family

Example: Inter

typeShowPopupstringOptional

Popup display type

isAutoClosePopUpbooleanOptional

Auto-close popup after delay

closingPopUpTimenumberOptional

Auto-close delay in seconds

Example: 10

frequencyShowPopupstringOptional

Display frequency

isShowSubscribeNewsletterbooleanOptional

Show newsletter subscribe checkbox

Responses

200

Referral branding updated

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

400

Validation error or no valid fields

application/json

put/rest_api/v2/shop/branding/referral

PUT /rest_api/v2/shop/branding/referral 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: 126

{
  "brandColor": "#6366F1",
  "colorType": "custom-solid",
  "customSolidColor": "#6366F1",
  "isAutoClosePopUp": true,
  "closingPopUpTime": 10
}

{
  "success": true,
  "data": {
    "brandColor": "#6366F1",
    "textColor": "#FFFFFF",
    "actionBgColor": "text",
    "actionTextColor": "text",
    "colorType": "template",
    "customSolidColor": "text",
    "themeTextFont": "Inter",
    "typeShowPopup": "text",
    "isAutoClosePopUp": true,
    "closingPopUpTime": 10,
    "frequencyShowPopup": "text",
    "isShowSubscribeNewsletter": true
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Get reminder branding

get

/rest_api/v2/shop/branding/reminder

Reads proactive reminder branding configuration. Maps to admin Storefront → Branding → Reminder.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Responses

200

Reminder branding configuration

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

get/rest_api/v2/shop/branding/reminder

GET /rest_api/v2/shop/branding/reminder 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: */*

200

Reminder branding configuration

{
  "success": true,
  "data": {
    "showUnusedDiscount": true,
    "unusedDiscountHeading": "text",
    "unusedDiscountButton": "text",
    "showRewardRedemption": true,
    "rewardRedemptionHeading": "text",
    "rewardRedemptionButton": "text",
    "showMilestoneAchieved": true,
    "milestoneAchievedHeading": "text",
    "autoCloseAfter": 10,
    "floatBtnPosition": "left-bottom",
    "reminderPriority": [
      "text"
    ]
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

Update reminder branding

put

/rest_api/v2/shop/branding/reminder

Partial update for proactive reminder branding. Triggers metafield sync.

Authorizations

X-Joy-Loyalty-App-KeystringRequired

X-Joy-Loyalty-Secret-KeystringRequired

Body

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

showUnusedDiscountbooleanOptional

Show unused discount reminder

unusedDiscountHeadingstringOptional

Unused discount heading text

unusedDiscountButtonstringOptional

Unused discount button text

showRewardRedemptionbooleanOptional

Show reward redemption reminder

rewardRedemptionHeadingstringOptional

Reward redemption heading text

rewardRedemptionButtonstringOptional

Reward redemption button text

showMilestoneAchievedbooleanOptional

Show milestone achieved reminder

milestoneAchievedHeadingstringOptional

Milestone heading text

autoCloseAfternumberOptional

Auto-close delay in seconds

Example: 10

floatBtnPositionstring · enumOptional

Reminder button position

Possible values:

reminderPrioritystring[]Optional

Reminder display order

Responses

200

Reminder branding updated

application/json

successbooleanOptionalExample: true

metaobjectOptional

Additional metadata such as counts and pagination

messagestringOptionalExample: Operation completed successfully

timestampstring · date-timeOptionalExample: 2023-07-28T07:27:54.123Z

400

Validation error or no valid fields

application/json

put/rest_api/v2/shop/branding/reminder

PUT /rest_api/v2/shop/branding/reminder 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: 47

{
  "showUnusedDiscount": true,
  "autoCloseAfter": 15
}

{
  "success": true,
  "data": {
    "showUnusedDiscount": true,
    "unusedDiscountHeading": "text",
    "unusedDiscountButton": "text",
    "showRewardRedemption": true,
    "rewardRedemptionHeading": "text",
    "rewardRedemptionButton": "text",
    "showMilestoneAchieved": true,
    "milestoneAchievedHeading": "text",
    "autoCloseAfter": 10,
    "floatBtnPosition": "left-bottom",
    "reminderPriority": [
      "text"
    ]
  },
  "meta": {},
  "message": "Operation completed successfully",
  "timestamp": "2023-07-28T07:27:54.123Z"
}

PreviousShop NextTranslations

Last updated 3 months ago

Branding

Get branding overview

Get widget branding

Update widget branding

Get referral branding

Update referral branding

Get reminder branding

Update reminder branding