Settings
Configure the widget with the config object, wire it to your own page with its settings, and drive it from the page URL.
The object the widget reads once, the moment its script runs. Write it before
the script tag.
SubblyCart.initialize(config)
takes the same object. Only apiKey is required.
Keys
apiKeyRequiredstringYour Storefront API key, from the Subbly admin under Settings, Developers.
A missing key throws Missing required apiKey config.
apiUrloptionalstringAPI the widget calls. Default https://api.subbly.co/storefront/v1/. An
empty string falls back to the default.
settingsoptionalobjectPage-integration settings: which links the widget catches, which element
opens it, which element shows the item count. Every key is on
Settings keys. Default {}.
languageCodeoptionalstringTwo-letter language of the widget. Without it, the widget takes the lang
query parameter of the page, then the lang attribute of <html>, then
the browser's language, and keeps the first two characters.
cartIdoptionalstringStart from a cart you already know. Default the subbly_cart_id cookie.
accessTokenoptionalstringSign a customer in at start-up. A valid token is written to the
subbly_access_token cookie. Default that cookie.
initoptionalbooleanfalse stops the automatic start-up; you then call
SubblyCart.initialize
yourself. Only the exact value false does this. Default true.
globalNameoptionalstringName of the global that gets the instance. A value that is not a non-empty
string is ignored. Default subblyCart.
sdkClientoptionalSubblyA Subbly.js client you already built. The widget uses it instead of creating its own.
checkoutOnlyoptionalbooleanStandalone checkout. The widget opens full screen and configures the item
from window.subblyCheckout.payload at once. Default false.
checkoutUrloptionalstringPage on your site that owns the checkout. The widget sends the customer
there instead of opening its own, and stands down on that path. It accepts
/checkout and /checkout/{cartId}; a bare page gets the current cart ID
appended on redirect.
cartSummaryUrloptionalstringPage on your site that owns the cart summary. Same behaviour as
checkoutUrl.
disableUrlsoptionalstring[]Paths on which the widget stands down. Default checkoutUrl (without its
cart ID) and cartSummaryUrl; an empty array keeps that default. Only the
pathname is matched, case-insensitively. * matches inside one segment,
** across segments. An entry without a wildcard also matches on a segment
boundary, so /checkout covers /checkout/success but not
/checkout-foo.
A full config object
Page-integration settings. They tie the widget to the markup on your own page:
which links it catches, which element opens it, which element shows the item
count. Set them in window.subblyConfig before the script runs, or pass them
to SubblyCart.initialize().
These are not the theme settings. Colours, typography and checkout behaviour
live in the shop's cart settings, which you override with
setSettings.
Keys
interceptProductLinksoptionalbooleanCatch clicks on Subbly buy links anywhere on the page, cancel the
navigation, and open the widget instead. See
Sell from your own links. Default false.
Before the widget finishes loading, a stub handler cancels these clicks. It does not remember them, so a click that early is dropped.
cartButtonoptionalbooleanShow the widget's own floating cart button. Default false. The button is
suppressed when the page already holds an a.subbly-cart element.
cartButtonImageoptionalstringURL of an image for the floating cart button, in place of the built-in
icon. It works only with cartButton: true. Default null; anything that
is not a string is ignored.
cartToggleEloptionalstring | HTMLElementCSS selector or element that opens and closes the widget. The default click
action is cancelled. Clicks are caught on document, so elements added
later still work. Default ''.
cartCounterEloptionalstring | HTMLElementCSS selector or element whose content the widget replaces with the number
of active items. It updates on CART_READY and CART_UPDATED, and after a
popstate event, where it waits up to 5 seconds for the element and then
300 ms more before writing. Default ''.
The widget also listens for a pushstate event, but nothing fires one: its
own patch of history.pushState dispatches locationchange instead. On a
framework that routes with pushState, update the element yourself from
CART_UPDATED.
localizationSettingsoptionalbooleanShow the currency and language picker in the widget header. Default
false.
disableSummaryViewoptionalbooleanHide the cart summary and use the checkout as the first view. Default
false. The ?disableSummaryView=1 query parameter does the same.
hideBundleItemsoptionalbooleanHide the products inside a bundle, in the summary and at the checkout.
Default false. The ?hideBundleItems=1 query parameter does the same.
Configure the widget
Query parameters the widget reads from the page URL when it starts. They make a plain link enough to drive the widget — a campaign link that applies a coupon, a referral link, a translated landing page.
Four of them are used once and then remembered as used: gift, coupon, r
and custom_setup_return_url. A bank confirmation that sends the customer back
to the same URL does not apply them twice.
Parameters
langoptionalstringLanguage of the widget, when languageCode is not in the config. The
widget takes the first two characters.
couponoptionalstringCoupon code to hold and apply once the cart fits it, as
setPendingCoupon
does. Used once.
giftoptionalstringAny value opens the gift view. Used once.
roptionalstringID of the referring customer. Used once.
emailoptionalstringPrefills the checkout email. customerEmail is a deprecated fallback.
firstNameoptionalstringPrefills the first name.
lastNameoptionalstringPrefills the last name.
marketingConsentoptionalstringPrefills the marketing opt-in.
tosConsentoptionalstringPrefills the terms checkbox.
customerExternalIdoptionalstringYour own ID for the customer. It is stored on the customer profile.
disableSummaryViewoptionalstringAny value hides the summary and uses the checkout as the first view.
hideBundleItemsoptionalstringAny value hides the products inside a bundle.
custom_success_urloptionalstringURL of your own receipt page, in place of the widget's.
custom_setup_return_urloptionalstringURL the customer returns to after a Stripe 3-D Secure check. Used once.
checkoutModeoptionalstringtest runs the checkout in test mode.
setup_intentoptionalstringSet by Stripe on the return redirect. payment_method_id and
redirect_status come with it.
A campaign link