Copy page

SubblyCart.js widget

SubblyCart.js is Subbly's cart and checkout widget. One script tag adds a cart, a product configurator and a full checkout to any website, in your shop's colours and languages. It talks to the Storefront API through Subbly.js, and it keeps the cart ID and the customer's access token in cookies, so a cart survives a page load.

Load

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

The widget reads window.subblyConfig the moment it runs, so write the config object first. Every method and property in this reference belongs to window.subblyCart, set once the subbly-cart-initialized event has fired on window.

Globals

Global	What it is
window.subblyConfig	The config object you write, read once while the widget loads.
window.SubblyCart	The widget class. Call SubblyCart.initialize(config) on it when you set init: false.
window.subblyCart	The initialized widget instance — the object every method and property in this reference belongs to. globalName renames it.
window.subblyCheckout	Optional. The item to configure in standalone checkout mode: an object with a payload key holding a ConfigureItemPayload, or null.

Cookies and storage

Key	Store	What it holds
subbly_cart_id	cookie, path /, 365 days	ID of the active cart.
subbly_access_token	cookie, path /, 365 days	Access token of the signed-in customer.
referral_id	cookie, 30 days	Referral ID from the r query parameter, kept for the next visit.
subbly_checkout_payload	localStorage	The item to configure in standalone checkout mode, tied to one shop and cart.

Errors

The widget throws a plain Error with a readable message — The cart is not initialized, for example. Calls that reach the API reject with the Subbly.js error object, which carries a code: not_found, bad_request, out_of_stock, payment_requires_action, user_email_is_not_unique or unauthenticated.

Handle a failure
try {
  await subblyCart.applyCoupon('WELCOME10')
} catch (err) {
  console.warn(err.code ?? err.message)
}

To install the widget, wait for it, and set every key of window.subblyConfig, see the Cart widget article.