Copy page

Subbly.js SDK

Subbly.js is Subbly's browser-side JavaScript library. It calls the Storefront API for you, holds one cart per page, and keeps the cart ID and the customer access token in browser cookies. Subbly.init resolves with an SDK instance; every method in this reference is a method of that instance.

The SDK emits no events: it has no emitter and dispatches no DOM events. The events you may have seen in Subbly belong to the cart widget, a separate product.

Load

Start the SDK
import Subbly from '@subbly/sdk'

const subbly = await Subbly.init({ apiKey: 'API_KEY' })

The package also ships a browser bundle, https://cdn.jsdelivr.net/npm/@subbly/sdk, that defines the global Subbly. It is the class, not an instance, so you still call Subbly.init(config).

Cookies

The SDK writes two cookies, each for 365 days on path=/:

• subbly_cart_id — the cart, written by Subbly.init when you pass loadCart, and by subbly.cart.create.
• subbly_access_token — the customer access token, written by the authentication methods and emptied by subbly.auth.logout.

Both are plain cookies. The SDK sets no Secure, HttpOnly or SameSite attribute, so any script on the host can read them.

Amounts and dates

Amounts are whole numbers in the minor unit of the currency: 1250 in a USD cart means $12.50. Dates and timestamps are strings.

Currency

The product, bundle and survey methods take an optional headers object as their last argument. Set x-currency on it to price that one response in another currency. When you leave it out, the SDK sends the currency you set with subbly.setCurrency; when you set neither, it sends no currency header.

The subscription methods also take headers, but the SDK adds no currency to them.

setCurrency does not change the cart. The cart has its own currencyCode; change it with subbly.cart.update({ currencyCode }). When Subbly.init loads a cart, it calls setCurrency with the cart currency for you.

Price one product in another currency
subbly.setCurrency('USD')

const product = await subbly.products.load(123)
const inEuros = await subbly.products.load(123, {}, { 'x-currency': 'EUR' })

Expand parameters

Most methods that return a cart or a subscription take an optional params object with an expand list. Each entry names a relation the API should fill in. A relation you do not name comes back null, so ask for what you need to render.

The cart methods accept coupon, gift_card, items.product, items.product.parent, items.product.parent.pricings, items.bundle.items.product, items.bundle.items.product.parent, items.metadata, shipping_method, shipping_address, payment_method, billing_address, metadata and shipping_carrier. The funnel accepts that return a cart take the same list.

The subscription methods accept product, product.parent, bundle.items.product, bundle.items.product.parent, metadata, addons, discounts and cancellations.

The funnel fetches accept parent, which loads the parent product of each offered variant or plan.

Load a cart with its items and coupon
await subbly.cart.load(cartId, {
  expand: ['items.product', 'items.product.parent', 'coupon']
})

Errors

A failed request rejects with a plain object, not an Error. So error instanceof Error is false and error.message may be missing. Read error.code instead.

Handle an error
try {
  await subbly.cart.addItem({ productId: 3301 })
} catch (error) {
  if (error.code === 'out_of_stock') {
    // tell the customer
  }
}

The codes are:

code	What happened
not_found	The record does not exist.
bad_request	The request or the payload is invalid.
out_of_stock	A product or a survey answer ran out.
payment_requires_action	The card needs 3-D Secure. The object also carries paymentIntentId.
user_email_is_not_unique	The email already has an account.
unauthenticated	There is no valid access token.

When the response has no body, the rejection is a real Error carrying the HTTP status text instead. Handle both shapes.

Two rejections are plain Error objects instead, with no code:

• Error('Missing required apiKey config') — Subbly.init with no argument, or with an empty or missing apiKey. init is async, so it rejects.
• Error('Cart ID is required') — subbly.cart.load with no ID given and none held.

To install, configure and update the library, see the Subbly.js SDK article.