API Reference
Start typing to search…

Tiered Progress Bar Methods

SmartCart.addFreeProduct ⇒ void

Adds a free gift to the cart

SmartCart.addSingleVariantFreeProduct

Adds the only available variant of a free gift product to the cart (used when there is only one variant available, which is either in variant_ids, or variants array)

SmartCart.calculatePercentageWithNormalTierMinimums ⇒ number

Calculates the progress bar's percentage when there is no Free Shipping On Subscription option enabled / satisfied

SmartCart.calculatePercentageWithSubscriptionProduct ⇒ number

Calculates the progress bar's percentage when there is a Free Shipping On Subscription option enabled + satisfied

SmartCart.freeProductOptions ⇒ Array

Gets the options for a free gift product - either all variants or selected variants

SmartCart.freeProductPrompt ⇒ string

Gets text for the Free Product button - based on the product's status

SmartCart.freeProductStyles ⇒ object | void

Gets the product's background image / styles

SmartCart.freeProductTileStyle ⇒ object | undefined

Gets the product's tile width, based on the number of earned products

SmartCart.getBarForLocation ⇒ object

Get progress bar settings based on location

SmartCart.getCurrentTier ⇒ object | null

Gets current tier

SmartCart.getEarnedProducts ⇒ Array.<object>

Gets the list of earned products from the bar

SmartCart.getFreeVariantTitle ⇒ string

Gets the gift product's variant title

SmartCart.getGiftAreaTitle ⇒ string

Gets the Gift Area Title to display above the Gift Area

SmartCart.getProductsWithoutSelection ⇒ Array.<object>

Gets the earned gifts in the cart that don't have a variant selected

SmartCart.getProgressBarSettings ⇒ object | null

Get the progress bar settings object

SmartCart.getProgressStepIconSize ⇒ object

Utility helper for getting the style object with configured sizes

SmartCart.getSpendToNextTier ⇒ number

Gets the difference between the subtotal and the next tier's minimum

SmartCart.getTierCompletedText ⇒ string

Get the text for the completed tier

SmartCart.getTierFeedbackText ⇒ string

Get the text for the current tier (either in progress or completed)

SmartCart.getTierLabel ⇒ string

Gets the step label for a given tier

SmartCart.getTierMinimum ⇒ number | null

Gets the minimum threshold for a given tier

SmartCart.getTieredBarProductData ⇒ object

Checks local storage for cached product data, and fetches any missing product data from the API

SmartCart.hasFreeShippingOnSubscription ⇒ boolean

Determine if Free Shipping should be satisfied by a subscription product in the Cart

SmartCart.hasGiftSelection ⇒ boolean

Determine if the gift product requires a customer variant selection

SmartCart.hasProgressPrompt ⇒ boolean | string

Determine if the progress bar has a prompt for the current tier

SmartCart.hasTierProgress ⇒ boolean

Determine if there is any progress to show in the progress bar

SmartCart.isGiftItem ⇒ boolean

Determines whether a cart item is a free gift item from the progress bar

SmartCart.isProgressBarEnabled ⇒ boolean

Determine if the progress bar is enabled

SmartCart.progressBarSubtotal ⇒ number

Gets the current subtotal for the TPB, with some exclusion logic

SmartCart.progressStepMaxWidth ⇒ string

Utility helper for getting the max width of the tiers for CSS

SmartCart.progressTierIcon ⇒ string

Utility helper for getting the icon for a given tier

SmartCart.progressTierReached ⇒ boolean

Determines if the tier has been reached based on the subtotal

SmartCart.removeAllFreeGifts

Removes all free gifts from the cart

SmartCart.removeFreeProduct

Deselects a free gift from the TPB Gift Area:

  • Updates the product status to loading
  • Removes the gift from the cart
  • Updates the product status to removed
  • Adds the gift to the declined gifts cookie
SmartCart.selectFreeProductVariant

Handles the selection of a free gift variant in the bar

SmartCart.shouldFilterOutOfStockVariantsFromTier ⇒ boolean

Determines whether Out of Stock variants should be hidden from the progress bar

SmartCart.shouldRenderEarnedGift ⇒ boolean

Determines whether a gift product in the earned products array should be rendered with the bar (helpful to prevent rendering out chosen gifts with the bar while in Line Item Mode)

SmartCart.shouldRenderGiftArea ⇒ boolean

Determines whether the Gifts Area should be rendered based on the progress bar settings and earned products state

SmartCart.shouldRenderGiftAreaTitle ⇒ boolean

Determine if the Gift Area Title should be used

SmartCart.tierCompleteIcon ⇒ string

Utility helper for getting the icon for a given tier (Complete)

SmartCart.tierProgressIcon ⇒ string

Utility helper for getting the icon for a given tier (In Progress)

SmartCart.tiersPercentageComplete ⇒ string | number

Calculates the progress bar's percentage completed

SmartCart.updateFreeProducts

Updates the free products in the cart based on the current subtotal. This contains the primary logic for the progress bar cart management

SmartCart.addFreeProduct ⇒ void

Adds a free gift to the cart

Param

Type

Description

product

object

The product object

SmartCart.addSingleVariantFreeProduct

Adds the only available variant of a free gift product to the cart
(used when there is only one variant available, which is either in variant_ids, or variants array)

Param

Type

Description

product

object

The product object

SmartCart.calculatePercentageWithNormalTierMinimums ⇒ number

Calculates the progress bar's percentage when there is no Free Shipping On Subscription option enabled / satisfied

Returns: number - The percentage as a number

Param

Type

Description

bar

object

The progress bar object

SmartCart.calculatePercentageWithSubscriptionProduct ⇒ number

Calculates the progress bar's percentage when there is a Free Shipping On Subscription option enabled + satisfied

Returns: number - The percentage as a number

Param

Type

Description

bar

object

The progress bar object

SmartCart.freeProductOptions ⇒ Array

Gets the options for a free gift product - either all variants or selected variants

Returns: Array - Array of variant objects

Param

Type

Description

product

object

The product object (from the earnedProducts array)

SmartCart.freeProductPrompt ⇒ string

Gets text for the Free Product button - based on the product's status

Returns: string - The text for the button

Param

Type

Description

product

object

The product object

SmartCart.freeProductStyles ⇒ object | void

Gets the product's background image / styles

Returns: object | void - The styles object

Param

Type

Description

product

object

The product object

freeProductTileStyle ⇒ object | undefined

Deprecated

Gets the product's tile width, based on the number of earned products

Returns: object | undefined - The styles object

Param

Type

Description

bar

object

The progress bar object

SmartCart.getBarForLocation ⇒ object

Get progress bar settings based on location

Returns: object - Progress bar settings object for the current location or default bar

Param

Type

Description

countryCode

string

Country code for the current location

SmartCart.getCurrentTier ⇒ object | null

Gets current tier

Returns: object | null - Returns a tier object or null

Param

Type

Description

bar

object

The progress bar object

SmartCart.getEarnedProducts ⇒ Array.<object>

Gets the list of earned products from the bar

Returns: Array.<object> - The list of earned products

Param

Type

Description

bar

object

The progress bar object

SmartCart.getFreeVariantTitle ⇒ string

Gets the gift product's variant title

Returns: string - The applied gift variant title

Param

Type

Description

product

object

The product object

SmartCart.getGiftAreaTitle ⇒ string

Gets the Gift Area Title to display above the Gift Area

Returns: string - The Gift Area Title

Param

Type

Description

bar

object

The progress bar object

SmartCart.getProductsWithoutSelection ⇒ Array.<object>

Gets the earned gifts in the cart that don't have a variant selected

Returns: Array.<object> - The earned products in the cart that don't have a variant selected

Param

Type

Description

bar

object

The progress bar object

SmartCart.getProgressBarSettings ⇒ object | null

Get the progress bar settings object

Returns: object | null - The progress bar settings object | null\

SmartCart.getProgressStepIconSize ⇒ object

Utility helper for getting the style object with configured sizes

Returns: object - Returns the style object with width and height defined for the image

Param

Type

Description

tier

object

The tier object

SmartCart.getSpendToNextTier ⇒ number

Gets the difference between the subtotal and the next tier's minimum

Returns: number - The difference as a number

Param

Type

Description

bar

object

The progress bar object

SmartCart.getTierCompletedText ⇒ string

Get the text for the completed tier

Returns: string - The completed tier text

Param

Type

Description

bar

object

The progress bar object

tier

object

The tier object

SmartCart.getTierFeedbackText ⇒ string

Get the text for the current tier (either in progress or completed)

Returns: string - The current tier text

Param

Type

Description

bar

object

The progress bar object

SmartCart.getTierLabel ⇒ string

Gets the step label for a given tier

Returns: string - Returns the label as a string

Param

Type

Description

tier

object

The tier object

SmartCart.getTierMinimum ⇒ number | null

Gets the minimum threshold for a given tier

Returns: number | null - Returns the minimum threshold as a number or null

Param

Type

Description

tier

object

The tier object

SmartCart.getTieredBarProductData ⇒ object

Checks local storage for cached product data, and fetches any missing product data from the API

Returns: object - The updated progress bar object

Param

Type

Description

bar

object

The progress bar object

SmartCart.hasFreeShippingOnSubscription ⇒ boolean

Determine if Free Shipping should be satisfied by a subscription product in the Cart

Returns: boolean - Boolean indicating whether Free Shipping should be satisfied by a subscription product\

SmartCart.hasGiftSelection ⇒ boolean

Determine if the gift product requires a customer variant selection

Returns: boolean - Boolean indicating whether the gift product has a variant selection

Param

Type

Description

product

object

The gift product object

SmartCart.hasProgressPrompt ⇒ boolean | string

Determine if the progress bar has a prompt for the current tier

Returns: boolean | string - A boolean value or a truthy string indicating whether the progress bar has a prompt or not

Param

Type

Description

bar

object

The progress bar object

SmartCart.hasTierProgress ⇒ boolean

Determine if there is any progress to show in the progress bar

Returns: boolean - Boolean indicating whether there is any progress to show\

SmartCart.isGiftItem ⇒ boolean

Determines whether a cart item is a free gift item from the progress bar

Returns: boolean - Boolean indicating whether the item is a free gift item

Param

Type

Description

item

object

Shopify cart item object

SmartCart.isProgressBarEnabled ⇒ boolean

Determine if the progress bar is enabled

Returns: boolean - Boolean indicating whether the progress bar is enabled or not\

SmartCart.progressBarSubtotal ⇒ number

Gets the current subtotal for the TPB, with some exclusion logic

Returns: number - the current subtotal (with exclusions)\

SmartCart.progressStepMaxWidth ⇒ string

Utility helper for getting the max width of the tiers for CSS

Returns: string - Returns the max width as a string (percentage for CSS)

Param

Type

Description

bar

object

The progress bar object

SmartCart.progressTierIcon ⇒ string

Utility helper for getting the icon for a given tier

Returns: string - Returns the icon as an HTML string

Param

Type

Description

tier

object

The tier object

SmartCart.progressTierReached ⇒ boolean

Determines if the tier has been reached based on the subtotal

Returns: boolean - Boolean indicating whether the tier has been reached

Param

Type

Description

tier

object

The tier object

SmartCart.removeAllFreeGifts

Removes all free gifts from the cart

SmartCart.removeFreeProduct

Deselects a free gift from the TPB Gift Area:

  • Updates the product status to loading
  • Removes the gift from the cart
  • Updates the product status to removed
  • Adds the gift to the declined gifts cookie

Param

Type

Description

product

object

The earned product object (from the bar.earnedProducts array)

callback

function

The callback function to run after the gift has been removed

SmartCart.selectFreeProductVariant

Handles the selection of a free gift variant in the bar

Param

Type

Description

event

object

The event object

product

object

The product object

SmartCart.shouldFilterOutOfStockVariantsFromTier ⇒ boolean

Determines whether Out of Stock variants should be hidden from the progress bar

Returns: boolean - Boolean indicating whether Out of Stock variants should be hidden for this tier

Param

Type

Description

tier

object

The tier object

SmartCart.shouldRenderEarnedGift ⇒ boolean

Determines whether a gift product in the earned products array should be rendered with the bar
(helpful to prevent rendering out chosen gifts with the bar while in Line Item Mode)

Returns: boolean - Boolean indicating whether the gift product should be rendered with the bar

Param

Type

Description

bar

object

The progress bar object

product

object

The gift product object

SmartCart.shouldRenderGiftArea ⇒ boolean

Determines whether the Gifts Area should be rendered based on the progress bar settings and earned products state

Returns: boolean - Boolean indicating whether the Gifts Area should be rendered

Param

Type

Description

bar

object

The progress bar object

SmartCart.shouldRenderGiftAreaTitle ⇒ boolean

Determine if the Gift Area Title should be used

Returns: boolean - Boolean indicating whether the Gift Area Title should be used

Param

Type

Description

bar

object

The progress bar object

SmartCart.tierCompleteIcon ⇒ string

Utility helper for getting the icon for a given tier (Complete)

Returns: string - Returns the icon as an HTML string

Param

Type

Description

tier

object

The tier object

SmartCart.tierProgressIcon ⇒ string

Utility helper for getting the icon for a given tier (In Progress)

Returns: string - Returns the icon as an HTML string

Param

Type

Description

tier

object

The tier object

SmartCart.tiersPercentageComplete ⇒ string | number

Calculates the progress bar's percentage completed

Returns: string | number - The percentage as a string or number

Param

Type

Description

bar

object

The progress bar object

returnInt

boolean

Indicates whether to return an integer or a string

SmartCart.updateFreeProducts

Updates the free products in the cart based on the current subtotal.
This contains the primary logic for the progress bar cart management