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](/reference/subbly-sdk), and it keeps the cart ID and the customer's access token in cookies, so a cart survives a page load. ## Load ```html title="Embed the widget" ``` 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`](/reference/cart-widget/methods#configure-item), 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`. ```js title="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](/developer-resources/cart-widget).