Subbly Docs

Guide

Open the cart widget with a button on the page

To toggle cart widget visibility with your cart button, pass button CSS selector as cartToggleEl setting in subblyConfig.

In the example below we can use .cart-button selector to configure cart widget.


<button class="cart-button">
  Cart
</button>

And update cart widget config as following:


<script>
  window.subblyConfig = {
    apiKey: 'API_KEY',
    settings: {
      cartToggleEl: '.cart-button'
    }
  }
</script>

By adding cartToggleEl setting, every matching button on the page will toggle cart widget's visibility.

Additionally, use cartCounterEl setting to specify all the elements on the page that will be updated with the current count of product in the cart.

Use built-in floating button

If you want to use the Subbly floating cart button, you can set the cartButton settings parameter.


<script>
  window.subblyConfig = {
    apiKey: 'API_KEY',
    settings: {
      cartButton: true
    }
  }
</script>

Add a product to cart

SubblyCart.js offers an easy way to create buy buttons on your page with interceptProductLinks setting.


<script>
  window.subblyConfig = {
    apiKey: 'API_KEY',
    settings: {
      interceptProductLinks: true
    }
  }
</script>

This will inform the widget to look up all the products links on the page and handle them buy opening product configuration in the widget.

The widget will look for links with the following structure:

  1. Links that have URL that contains /checkout/buy/PRODUCT_ID.
<a href="https://example.com/checkout/buy/PRODUCT_ID">
  Buy
</a>
  1. Links that have data-subbly-product attribute with a product ID.
<a href="#" data-subbly-product="PRODUCT_ID">
  Buy
</a>

Replacing PRODUCT_ID with the actual product ID the button will trigger SubblyCart.js when clicked.

In addition to products, the widget also captures links for bundle and survey flow customizations in the following format:

  • Bundle
<a href="https://example.com/checkout/buy/bundle/BUNDLE_ID">
  Buy a bundle
</a>
  • Survey flow
<a href="https://example.com/checkout/buy/survey/SURVEY_ID">
  Start a survey flow
</a>

Adding products programmatically

Using configureItem and addItem SubblyCart.js methods you can add products to cart at any time. For example, when a button is clicked


<script>
  const myButton = document.querySelector('.my-custom-button')

  myButton.addEventListener('click', () => {
    subblyCart.configureItem({
      productId: 111,
      quantity: 1
    })
  })
  // or
  myButton.addEventListener('click', () => {
    subblyCart.addItem({
      productId: 111,
      quantity: 1
    })
  })
</script>

When to use configureItem and addItem?

  • configureItem will start product configuration flow if provided product ID is not finalized: requires plan, variant selection or survey.
  • addItem will expects finalized product and will attempt to add the product to cart. Using product ID of non-finalized product will result in an error and product will not be added to the cart.

See more detailed information on possible parameters in SubblyCart.js reference

Language

By the default, the cart widget is using your primary translation which is set on the Storefront Translationsopen in new window page in Subbly Admin. There are multiple ways to set an active translation for the cart widget.

Specify language code in the subblyConfig


<script>
  window.subblyConfig = {
    apiKey: 'API_KEY',
    languageCode: 'es'
  }
</script>

Set the language on your page

When loaded the cart widget will check your page for standard HTML language specifications

  1. From <html> tag lang attribute.

<html lang="es">
  1. From query parameter lang in the current URL.

https://example.com?lang=es

Using SubblyCart.js method setLanguage


<script>
  window.addEventListener('subbly-cart-initialized', () => {
    subblyCart.setLanguage('es')
  })
</script>

Currency

With multi-currency enabled, it is possible to change cart currency by using SubblyCart.js setCurrency method. Currency can be set once for a cart and will persist between page reloads.


<script>
  window.addEventListener('subbly-cart-initialized', () => {
    subblyCart.setCurrency('EUR')
  })
</script>

Add a coupon or a gift card

To add a coupon, you can use the following code:

<script>
  window.addEventListener('subbly-cart-initialized', () => {
    subblyCart.applyCoupon('COUPON_CODE')
  })
</script>

To add a gift card, you can use the following code:

<script>
  window.addEventListener('subbly-cart-initialized', () => {
    subblyCart.applyGiftCard('GIFT_CARD_CODE')
  })
</script>

Open gift configuration view

<script>
  window.addEventListener('subbly-cart-initialized', () => {
    subblyCart.configureGift(null, true)
  })
</script>

Use subblyCart.configureGift(null, false) to show gift configuration only once the customer opens the widget.