Properties
Read the cart, the shop, the language and currency in use, the SDK client, and the event emitter.
The current cart: every cart field, plus the cart methods of the SDK. It is one live object, not a snapshot — the SDK writes the new data into the same object after every call, so a reference you store keeps showing current data. Clone it when you need a snapshot.
Treat it as read-only and change the cart through the widget methods. The SDK methods on it skip the widget's own store, so the panel does not refresh and no event fires.
The cart is ready as soon as the widget is initialized.
Cart properties
cartCartModelThe cart.
Cart methods
load(cartId?: string, params?: object) => Promise<CartModel>Re-reads the cart from the API. The type declares the argument as a cart item ID; the code takes a cart ID.
create(payload?: CartUpdatePayload, params?: object) => Promise<CartModel>Creates a cart and stores its ID in the subbly_cart_id cookie.
update(payload: CartUpdatePayload, params?: object) => Promise<CartModel>Applies cart-level changes.
addItem(payload: CartItemAddPayload, params?: object) => Promise<CartModel>Adds a line to the cart.
updateItem(cartItemId: string, payload: object, params?: object) => Promise<CartModel>Changes a line in the cart.
removeItem(cartItemId: string, params?: object) => Promise<CartModel>Removes a line from the cart.
getGiftingDates() => Promise<object>Lists the dates a gift subscription can start on.
getShippingMethods(params: object) => Promise<ShippingMethodDelivery[]>Lists the delivery methods for the cart.
getLocalPickups() => Promise<ShippingMethodPickup[]>Lists the pickup points for the cart.
attachCustomer(params?: object) => Promise<CartModel>Attaches the signed-in customer to the cart.
Read the cart
Public information about the shop: branding, currencies, languages, settings,
plan limits and shipping countries. The widget loads it once while it starts.
Like the cart, it is one live object; loadShop() refreshes it in place.
Shop properties
shopSubblyShopThe shop.
List the currencies the shop sells in
The currency and the language the widget runs on. Reading it builds a fresh plain object every time, so what you get is a snapshot.
Properties
currencyCodestringCurrency of the cart, as an ISO 4217 code. It falls back to the shop's default currency while the cart has none.
languageCodestringTwo-letter code of the language the widget shows, such as en.
Read the state
The Subbly.js client the widget uses, for Storefront API calls of your own. Sharing one client keeps the widget and your code on the same cart, customer, language and currency.
Calls you make on the client do not go through the widget's store, so the panel does not refresh and no widget event fires. Use the widget methods to change the cart.
Properties
VERSIONstringVersion of the SDK.
configobjectThe client configuration: apiKey, apiUrl and lang.
setCurrency(code: string) => voidRe-prices the products, bundles and surveys the client loads next. It does
not change the cart; use subblyCart.setCurrency for that.
setLanguage(code: string) => voidSets the language the API answers in.
Modules
addressesmodulelist, store, delete.
authmoduleisAuthenticated, checkAuthenticated, login, registered, register,
otp, otpLogin, social, logout, getAccessToken.
bundlesmodulelist, load, loadItems, loadGroups, quote, setCurrency.
cartmoduleThe same object as subblyCart.cart.
checkoutmodulepurchase.
countriesmodulelist.
customersmoduleupdate, me, referral. All three need a signed-in customer.
funnelsmoduleprePurchaseFetch, prePurchaseRefresh, prePurchaseAccept,
prePurchaseReject, midPurchaseFetch, midPurchaseAccept,
midPurchaseReject, postPurchaseFetch, postPurchaseAccept,
postPurchaseReject.
leadmodulesubscribe.
metafieldmodulelist.
paymentIntentsmodulegetPaymentIntent, confirm.
pickupInfomodulelist, store, delete.
productsmodulelist, load, loadVariant, loadPlan, setCurrency.
shopmoduleload. The same object as subblyCart.shop.
stockmodulesubscribe.
subscriptionsmodulelist, load, update, updatePreferences, updateBundle, loadItem,
updateItem, updateItemBundle, updateItemPreferences.
surveysmoduleload, setCurrency.
walletmodulestore, list, setup, setupIntent.
Call the Storefront API
The event emitter of the widget. events.type holds the event names, and every
name equals its own value, so events.type.CART_OPEN is 'CART_OPEN'. The
emitter comes from tiny-typed-emitter, which follows the Node
EventEmitter API.
Properties
typeobjectThe event names: CART_READY, CART_UPDATED, CART_OPEN, CART_CLOSE,
CART_RESET, EMAIL_COLLECTED, PURCHASE_COMPLETED, SIGN_IN,
SIGN_UP and SIGN_OUT.
on(type, handler) => thisAdds a handler. addListener is an alias.
once(type, handler) => thisAdds a handler that runs for one emission.
off(type, handler) => thisRemoves a handler. removeListener is an alias.
removeAllListeners(type?) => thisRemoves every handler, of one event or of all of them.
prependListener(type, handler) => thisAdds a handler at the front of the list. prependOnceListener does the
same for one emission.
eventNames() => string[]Lists the events that have handlers.
listenerCount(type) => numberCounts the handlers of an event.
listeners(type) => handler[]Lists the handlers of an event. rawListeners keeps the once wrappers.
setMaxListeners(count) => thisSets how many handlers one event takes before Node warns.
getMaxListeners reads it back.
emit(type, ...args) => booleanInternal. The widget emits its own events; do not call this.
Subscribe and unsubscribe