Subbly Docs

SubblyCart.js widget

Installation

Include SubblyCart.js on every page of your site where customers can use cart widget.

<script>
  window.subblyConfig = {
    apiKey: 'API_KEY'
  };
</script>
<script type="module" src="https://assets.subbly.co/cart/cart-widget.js"></script>

It is recommended to include the script before the closing </body> tag.

SubblyCart script is loaded asynchronously, which means it won't block the page rendering and may not be available immediately after the script tag is loaded. To verify that the widget has loaded listen to the global event subbly-cart-initialized, that is emitted after the script has finished loading:

window.addEventListener('subbly-cart-initialized', () => {
  // window.subblyCart is now available 
})

When SubblyCart is included on the page, it will automatically:

  • load the shop information
  • load the cart or create a new one
  • render the widget in the closed state

Manual initialization (advanced)

It is possible to load SubblyCart and initialize it manually at a later time. Use init config parameter to prevent default behavior:

<script>
  window.subblyConfig = {
    init: false
  };
</script>
<script type="module" src="https://assets.subbly.co/cart/cart-widget.js"></script>

And manually initialize the cart widget:

window.addEventListener('subbly-cart-loaded', () => {
  SubblyCart.initialize({
    apiKey: 'API_KEY'
  })
})

window.addEventListener('subbly-cart-initialized', () => {
  // window.subblyCart is now available
})

Configuration

apiKey REQUIRED string

Your Subbly Storefront API key is required, as it provides identification and Cart Widget customization. To obtain your API key, visit Shop Settingsopen in new window in Subbly Admin.

Example: 0736e2ec-484a-4f73-bebe-4b0263ef16c6

languageCode optional string

Sets preferred storefront translation. Primary translation is used by default.

When not provided, Cart Widget will attempt to read the language from lang query parameter, or lang attribute from page's html tag.

Example: en

cartId optional string

Manually provide a Cart ID to initialize the cart widget with. By the default SubblyCart automatically manages the cart ID in secure browser cookies.

Example: 97affe36-cfab-459b-8220-d7fac2e49913

settings optional object

  • interceptProductLinks optional boolean
    Intercept and prevent default click behavior on every link that contains a URL with /checkout/buy/{productID} and /checkout/add/{productID}, or has data-subbly-product HTML attribute containing a product ID.

  • cartCounterEl optional string | HTMLElement
    A selector or an HTML element that will be updated with the current Cart items count.

  • cartToggleEl optional string | HTMLElement
    A selector or an HTML element that will open/close the SubblyCart widget

  • cartButton optional boolean Add a floating cart button on the page

  • cartButtonImage optional string URL to the image that will be used as a cart button. By default, a cart icon is used.

  • localizationSettings optional boolean Enable currency and language settings dropdown in the cart widget toolbar. By the default, localization settings dropdown is displayed only on the checkout part of the cart widget.

sdkClient optional object

Use previously configured instance of Subbly SDK. With sdkClient provided the required parameter apiKey can be omitted.

See Initializing Subbly JS SDK.

Extended settings example
window.subblyConfig = {
  apiKey: 'API_KEY',
  languageCode: 'es',
  settings: {
    interceptProductLinks: true,
    cartCounterEl: '#cartCounter',
    cartToggleEl: '#cartToggle',
    cartButton: true,
    cartButtonImage: 'https://example.com/cart-icon.png',
  }
}

Widget API

Initialized cart widget provides a set of methods and events.

Methods

open()

This method opens SubblyCart widget

Parameters
view optional string "summary" | "checkout"

By default the open method opens the cart summary. You can customize the behavior by passing the view as an argument.

subblyCart.open()
// To open the the checkout view
subblyCart.open('checkout')

close()

This method closes SubblyCart widget

subblyCart.close()

toggle()

This method changes SubblyCart widget visibility between open and close

subblyCart.toggle()

updateCart(payload)

Updates the Cart and reflects changes in the widget, even if the widget is closed.

Parameters
payload REQUIRED object

See CartUpdatePayload for complete reference.

Example:

subblyCart.updateCart({
  referralId: 555,
  currencyCode: 'EUR',
  couponCode: 'COUPON_CODE',
  giftCardCode: 'ba445a44-e446-47da-b496-97d569f59ff5',
  giftInfo: {
    startsAt: '2023-01-13',
    numberOfOrders: 2,
    message: 'A message for gifting person'
  }
})
Returns

Returns Promise that resolves with updated SubblyCart.cart

configureItem(configureItemPayload)

Adds a product to the cart and opens customization view if product is not finalized, e.i. requires customer to select a variant, pricing, or fill a survey.

Parameters
cartItemPayload REQUIRED object

See CartItemAddPayload for complete reference.

Subscription products:

  • productId REQUIRED number
  • options optional array
    A complete list of survey options with required properties:
    • questionId number
    • answers array Answer interface depends on the type of question it belongs to:
      • id number - required for select, multiple, quantity question types
      • content string - required only for survey question type text
      • quantity number - required only for survey question type quantity

One-time products:

  • productId REQUIRED number
  • quantity REQUIRED number
  • addon optional boolean Allowed only with subscription product in the cart. Default: false.
  • addonDuration optional 1 | null Allowed only with addon: true. Can be either null (forever) or 1 (once). Default: null.
  • giftCard optional object | null Gift card recipient details. Allowed only for gift card products and with quantity of 1. Default: null
    • customerEmail required string
    • customerName optional string | null
    • message optional string | null
Returns

A Promise that resolves with an object containing finalized property. If finalized is true, the product is added to the cart, otherwise, the product is not finalized and appropriate customization view is opened.

Example for a subscription product:

subblyCart.configureItem({
  productId: 555,
  options: [{
    questionId: 777,
    answers: [{
      id: 888,
      quantity: 3
    }] 
  }]
})

Example for a one-time product:

subblyCart.configureItem({
  productId: 555,
  quantity: 2,
  addon: true,
  addonDuration: 1
})

Example for a bundle:

subblyCart.configureItem({
  bundleId: 555
})

Example for a survey flow:

subblyCart.configureItem({
  surveyId: 555
})

addItem(payload)

Add a finalized product to the cart. Will throw an error if the product is not finalized, e.i. contains a parent product ID or missing required survey answers.

Parameters
payload REQUIRED object

See CartItemAddPayload.

Returns

A Promise that resolves with updated SubblyCart.cart

subblyCart.addItem({
  productId: 555,
  quantity: 1
})

updateItem(cartItemId, payload)

Update the cart item in the cart.

Parameters
cartItemId REQUIRED string
payload REQUIRED object

See cartItemPayload omitting productId.

subblyCart.updateItem('53c511f3-14bc-42b7-b548-07e697f3db19', {
  quantity: 2
})
Returns

A Promise that resolves with updated SubblyCart.cart

removeItem(cartItemId)

Parameters
cartItemId REQUIRED string
Returns

A Promise that resolves with updated SubblyCart.cart

Example:

subblyCart.removeItem('53c511f3-14bc-42b7-b548-07e697f3db19')

setLanguage(langCode)

Change the language of the widget

Parameters
langCode REQUIRED string

Example:

subblyCart.setLanguage('fr')

setCurrency(currencyCode)

Change the currency of the cart

Parameters
currencyCode REQUIRED string
Returns

A Promise that resolves with updated SubblyCart.cart

Example:

subblyCart.setCurrency('GBP')

applyCoupon(couponCode)

Applies a coupon to the cart

Parameters
couponCode REQUIRED string
Returns

A Promise that resolves with updated SubblyCart.cart

Example:

subblyCart.applyCoupon('COUPON_CODE')

removeCoupon()

Removes an applied coupon from the cart

Returns

A Promise that resolves with updated SubblyCart.cart

Example:

subblyCart.removeCoupon()

applyGiftCard(giftCardCode)

Applies a gift card code to the cart

Parameters
giftCardCode REQUIRED string
Returns

A Promise that resolves with updated SubblyCart.cart

Example:

subblyCart.applyGiftCard('ba445a44-e446-47da-b496-97d569f59ff5')

removeGiftCard()

Remove applied gift code card from the cart

Returns

A Promise that resolves with updated SubblyCart.cart

Example:

subblyCart.removeGiftCard()

resetCart()

Creates a new cart with current cart's currency code.

Example:

subblyCart.resetCart()
Returns

Returns Promise that resolves with updated SubblyCart.cart

setSettings(settings)

Update cart widget settings. Accepts partial settings object.

Parameters
settings REQUIRED object

See ShopCartSettings.

subblyCart.setSettings({
  accentColor: '#701eff'
})

configureGift(payload, boolean)

Open gift configuration view.

Parameters

payload REQUIRED null - Currently not supported.
boolean REQUIRED boolean - true to open the widget with gift configuration view, false to show gift customization view later, e.g. after product customization.
subblyCart.configureGift(null, true)

Properties

cart

SubblyCart interface that contains full information about the cart.

shop

SubblyShop interface that contains public information about the shop.

state

Cart Widget current state

{
  languageCode: string
  currencyCode: string
}

sdk

An instance of Subbly SDK

Events

Available events

  • CART_READY
    Emitted once when SubblyCart widget is rendered on the page.
subblyCart.events.on(subblyCart.events.type.CART_READY, (err, cart) => {
  // cart widget was mounted on the page
})
  • CART_UPDATED
    Emitted every time the cart is updated.
subblyCart.events.on(subblyCart.events.type.CART_UPDATE, (err, cart) => {
  // cart has been updated
})
  • CART_OPEN
    Emitted every time the widget is opened.
subblyCart.events.on(subblyCart.events.type.CART_OPEN, () => {
  // cart widget is opened
})
  • CART_CLOSE
    Emitted every time the widget is closed.
subblyCart.events.on(subblyCart.events.type.CART_CLOSE, () => {
  // cart widget is closed
})
  • CART_RESET
    Emitted when the cart has been re-created. May happen due to attempt to add an item to an already purchased cart.
subblyCart.events.on(subblyCart.events.type.CART_RESET, (err, cart) => {
  // new cart
})
  • EMAIL_COLLECTED
    Emitted after capturing the customer's email. For authenticated customers the event is emitted when the checkout form is opened. The data contains the email property.
subblyCart.events.on(subblyCart.events.type.EMAIL_COLLECTED, (err, data) => {
  const { email } = data
})
  • PURCHASE_COMPLETED
    Emitted after a successful cart purchase. The data contains the cart and purchase information
subblyCart.events.on(subblyCart.events.type.PURCHASE_COMPLETED, (err, data) => {
  const { cart, purchase } = data
})