Cart

Create and change the cart, and read the delivery options and dates for it.

subbly.cart is both the data and the methods. It carries every cart field straight on the object — subbly.cart.id, subbly.cart.items, subbly.cart.total — and the methods below change it. Each of those methods copies the response onto the same object and resolves with it, so the value you await and subbly.cart are one and the same. There is only ever one cart per SDK instance, and fields the response leaves out keep their old values.

Amounts are whole numbers in the minor unit of the cart currency; see Amounts and dates.

Most methods take an optional params.expand list; the values it accepts are under Expand parameters.

subbly.cart.create(payload?, params?)

Creates a new cart and stores its ID in the subbly_cart_id cookie for 365 days. It replaces whatever cart the SDK already held, so call it once, and use subbly.cart.load to come back to a cart you already have.

The cookie is a plain one on path=/, with no Secure, HttpOnly or SameSite attribute.

Method parameters

payloadoptionalCartCreatePayload

What the new cart starts with. Pass null or leave it out for an empty cart. The TypeScript type is the wider update payload, but the create endpoint reads only the four fields below; set anything else with subbly.cart.update afterwards.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The cart, which is subbly.cart itself.


Create a cart
const cart = await subbly.cart.create()


Create a cart in a currency, with a coupon
const cart = await subbly.cart.create(
  { currencyCode: 'EUR', couponCode: 'WELCOME10' },
  { expand: ['coupon', 'items.product'] },
)

subbly.cart.load(cartId?, params?)

Loads a cart by ID into subbly.cart. Leave the ID out to refresh the cart the SDK already holds.

Unlike create, this does not write the cookie. Subbly.init writes it itself after a successful load.

Method parameters

cartIdoptionalstring

UUID of the cart. Leave it out to reload the cart already held. With no ID and no cart held, the call throws Error('Cart ID is required') at once, without reaching the network.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Load a cart by ID
const cart = await subbly.cart.load('aaea067c-6364-4157-82e9-71b6edfd84a0')


Refresh the cart in hand
await subbly.cart.load(undefined, { expand: ['items.product'] })

subbly.cart.update(payload, params?)

Changes the cart itself rather than its items: who is buying, where it ships, how it ships, which discounts apply, and when a subscription starts. Send only the fields you change.

Most of it works for a guest. Three fields point at records only a signed-in customer has: paymentMethodId, shippingAddressId and billingAddressId.

Method parameters

payloadRequiredCartUpdatePayload

The fields to change. Every one is optional.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Set the guest details
await subbly.cart.update({
  customer: {
    email: 'ada@example.com',
    firstName: 'Ada',
    lastName: 'Lovelace',
    tosConsent: true,
  },
})


Set the delivery address and the method
await subbly.cart.update({
  shippingAddress: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    phone: '+442071234567',
    addressOne: '12 Marylebone Road',
    addressTwo: null,
    city: 'London',
    zip: 'NW1 5JD',
    countryId: 826,
  },
  shippingMethodId: 91,
})


Remove the coupon
await subbly.cart.update({ couponCode: null })

subbly.cart.addItem(payload, params?)

Adds a product, a plan or a bundle to the cart. Adding the same one-time item again raises its quantity instead of making a second line.

The payload has a shape per kind of item. All three share productId, quantity and metadata; the rest depends on what you are adding.

Method parameters

payloadRequiredCartItemAddPayload

The item to add.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart. The call rejects with code: 'out_of_stock' when the product ran out.


Add a one-time product
await subbly.cart.addItem({ productId: 3301, quantity: 2 })


Add a subscription with survey answers
await subbly.cart.addItem({
  productId: 8801,
  options: [
    { questionId: 11, answers: [{ id: 41 }] },
    { questionId: 12, answers: [{ content: 'No nuts, please' }] },
  ],
})


Add a bundle
await subbly.cart.addItem({
  productId: 8801,
  quantity: 1,
  bundle: {
    items: [
      { productId: 3301, quantity: 2 },
      { productId: 3307, quantity: 1 },
    ],
    preferences: [{ attributeId: 9, values: [31] }],
  },
})

subbly.cart.updateItem(cartItemId, payload, params?)

Changes one line in the cart: the quantity, the survey answers, the gift details or the bundle contents. To change which product a line is for, remove it and add the new one.

Method parameters

cartItemIdRequiredstring

UUID of the line, from cart.items[].id.

payloadRequiredCartResourceUpdateItemPayload

What to change. Every field is optional, and the shape follows the kind of item the line holds.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Change the quantity
const [line] = subbly.cart.items

await subbly.cart.updateItem(line.id, { quantity: 3 })

subbly.cart.removeItem(cartItemId, params?)

Removes one line from the cart.

Method parameters

cartItemIdRequiredstring

UUID of the line, from cart.items[].id.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Remove an item
const [line] = subbly.cart.items

await subbly.cart.removeItem(line.id)

subbly.cart.getStartDates()

Gets the dates on which the subscription in the cart can start. Send the one the customer picks to subbly.cart.update as startsAt.

It uses the cart the SDK holds, so load or create a cart first.

ReturnsPromise<CartResourceStartDatesResponse>

The dates allowed. The API fills one of the two fields and sets the other to null: a fixed list of dates, or an open range. Handle both.


Get the start dates
const { availableDates, range } = await subbly.cart.getStartDates()

const startsAt = availableDates?.length ? availableDates[0] : range?.[0]

await subbly.cart.update({ startsAt })

subbly.cart.getGiftingDates()

Gets the dates on which a gift subscription in the cart can start. Send the one the customer picks to subbly.cart.update as giftInfo.startsAt.

ReturnsPromise<CartResourceGiftingDatesResponse>

The dates allowed, in the same shape subbly.cart.getStartDates returns.


Get the gifting dates
const { availableDates, range } = await subbly.cart.getGiftingDates()

const startsAt = availableDates?.length ? availableDates[0] : range?.[0]

await subbly.cart.update({
  giftInfo: {
    startsAt,
    numberOfOrders: 3,
    message: 'Happy birthday',
    recipientEmail: 'grace@example.com',
  },
})

subbly.cart.getShippingMethods(params)

Gets the delivery options available for the cart at a destination. Send the ID of the one the customer picks to subbly.cart.update as shippingMethodId.

Only countryId and zip are needed. Pass the rest when a carrier quotes on the full address.

Method parameters

paramsRequiredCartShippingMethodsParams

Where the order is going.

ReturnsPromise<ShippingMethodDelivery[]>

The delivery options. Read type first: it is shipping_option for a carrier delivery and local_delivery for the shop's own, and it decides which of the fields below are set.


Get the shipping methods
const methods = await subbly.cart.getShippingMethods({
  countryId: 826,
  zip: 'NW1 5JD',
  expand: ['carrier'],
})

await subbly.cart.update({ shippingMethodId: methods[0].id })

subbly.cart.getLocalPickups()

Gets the pick-up points available for the cart. Send the ID of the one the customer picks to subbly.cart.update as shippingMethodId, along with pickupInfo for who collects the order.

ReturnsPromise<ShippingMethodPickup[]>

The pick-up points. The array is empty when the shop offers none.


Get the pick-up points
const points = await subbly.cart.getLocalPickups()

await subbly.cart.update({
  shippingMethodId: points[0].id,
  pickupInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    phone: '+442071234567',
  },
})

subbly.cart.attachCustomer(params?)

Assigns the cart to the signed-in customer. It sets attached to true and customerId to their ID, and clears the guest details in customer. Call it after the customer signs in and before you charge the cart.

It needs a signed-in customer.

Method parameters

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The attached cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Attach the customer after a log-in
await subbly.auth.login({ email, password })
await subbly.cart.attachCustomer({ expand: ['items.product'] })

Last modified on September 15, 2026

Cart

Create and change the cart, and read the delivery options and dates for it.

Amounts are whole numbers in the minor unit of the cart currency; see Amounts and dates.

Most methods take an optional params.expand list; the values it accepts are under Expand parameters.

subbly.cart.create(payload?, params?)

The cookie is a plain one on path=/, with no Secure, HttpOnly or SameSite attribute.

Method parameters

payloadoptionalCartCreatePayload

currencyCodeoptionalstring

Currency of the cart, such as EUR. Defaults to the shop currency.

couponCodeoptionalstring | null

Coupon code to apply straight away.

giftCardCodeoptionalstring | null

Gift card code to apply straight away.

referralIdoptionalnumber | null

ID of the referral that led to this cart.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The cart, which is subbly.cart itself.

idstring

UUID of the cart. Pass it to subbly.checkout.purchase and to the funnel methods.

shopIdnumber

ID of the shop the cart belongs to.

statusstring

initialized, abandoned, expired, completed or restored. A completed cart cannot be changed.

attachedboolean

true once a signed-in customer owns the cart. subbly.cart.attachCustomer sets it.

createdAtstring

When the cart was created.

updatedAtstring

When the cart last changed.

currencyCodestring

Currency of the cart, such as USD. Change it with subbly.cart.update({ currencyCode }).

baseCurrencyCodestring

Base currency of the shop.

subTotalnumber

Sum of the lines before discount and tax.

discountTotalnumber

Total taken off by coupons, offers, referrals and gift cards.

taxTotalnumber

Total tax.

taxRatenumber

Cart-level tax rate. Single lines may use their own rate.

customsFeenumber

Customs charge on this order.

futureCustomsFeenumber

Customs charge on each later renewal.

adjustmentnumber

A manual correction. It may be negative.

totalnumber

Grand total, across what is charged now and what is charged later. Read summaryItems[].chargeNow to split the two.

balanceChangeobject

How much store credit the cart uses.

itemsCartItem[]

The lines the customer added. They hold no money fields; the prices live in summaryItems.

summaryItemsCartSummaryItem[]

The priced lines. Every item produces one or more of these, and shipping adds one of its own. Match them back with itemId.

discountsobject[]

The cart-level discounts.

customerIdnumber | null

ID of the customer who owns the cart. Set only after subbly.cart.attachCustomer.

customerobject | null

Guest details written straight onto the cart. null once a customer is attached. This is not a SubblyCustomer: id, userId and createdAt are always null.

couponCodestring | null

The coupon code on the cart.

couponCoupon | null

The coupon itself. The API sends it only when you ask for the coupon expand.

giftCardCodestring | null

The gift card code on the cart.

giftCardGiftCard | null

The gift card itself. The API sends it only when you ask for the gift_card expand.

referralIdnumber | null

ID of the referral that led to this cart.

giftInfoobject

Gift settings. Always an object; every member is null when the cart is not a gift.

startsAtstring | null

When the subscription starts. Pick a date from subbly.cart.getStartDates().

shippingAddressIdnumber | null

ID of the saved address or pick-up info used for delivery.

shippingAddressCustomerAddress | CustomerPickupInfo | null

The delivery address. The API sends it only when you ask for the shipping_address expand. A pick-up info arrives instead when the cart ships to a pick-up point; its fields are on the Pick-up info page.

billingAddressIdnumber | null

ID of the saved billing address.

billingAddressCustomerAddress | null

The billing address. The API sends it only when you ask for the billing_address expand. Same fields as shippingAddress.

shippingMethodIdnumber | null

ID of the delivery option chosen.

shippingMethodShippingMethod | null

The delivery option itself. The API sends it only when you ask for the shipping_method expand. Read type to tell a carrier delivery, a local delivery and a pick-up point apart.

shippingCarrierIdnumber | null

ID of the carrier chosen.

shippingCarrierobject | null

The carrier chosen, with id, name and serviceCodes. The API sends it only when you ask for the shipping_carrier expand.

shippingCarrierServicestring | null

The carrier service chosen, from serviceCodes.

paymentMethodIdnumber | null

ID of the payment method to charge. Only a signed-in customer has one.

paymentMethodPaymentMethod | null

The payment method itself. The API sends it only when you ask for the payment_method expand, and only for a signed-in customer.

metadataMetafield[] | null

Metafield values on the cart. The API sends them only when you ask for the metadata expand. The shape is on the Metafields page.

onboardingTemplateIdnumber | null

ID of the onboarding template applied to the cart.


Create a cart
const cart = await subbly.cart.create()


Create a cart in a currency, with a coupon
const cart = await subbly.cart.create(
  { currencyCode: 'EUR', couponCode: 'WELCOME10' },
  { expand: ['coupon', 'items.product'] },
)

subbly.cart.load(cartId?, params?)

Loads a cart by ID into subbly.cart. Leave the ID out to refresh the cart the SDK already holds.

Unlike create, this does not write the cookie. Subbly.init writes it itself after a successful load.

Method parameters

cartIdoptionalstring

UUID of the cart. Leave it out to reload the cart already held. With no ID and no cart held, the call throws Error('Cart ID is required') at once, without reaching the network.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Load a cart by ID
const cart = await subbly.cart.load('aaea067c-6364-4157-82e9-71b6edfd84a0')


Refresh the cart in hand
await subbly.cart.load(undefined, { expand: ['items.product'] })

subbly.cart.update(payload, params?)

Changes the cart itself rather than its items: who is buying, where it ships, how it ships, which discounts apply, and when a subscription starts. Send only the fields you change.

Most of it works for a guest. Three fields point at records only a signed-in customer has: paymentMethodId, shippingAddressId and billingAddressId.

Method parameters

payloadRequiredCartUpdatePayload

The fields to change. Every one is optional.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Set the guest details
await subbly.cart.update({
  customer: {
    email: 'ada@example.com',
    firstName: 'Ada',
    lastName: 'Lovelace',
    tosConsent: true,
  },
})


Set the delivery address and the method
await subbly.cart.update({
  shippingAddress: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    phone: '+442071234567',
    addressOne: '12 Marylebone Road',
    addressTwo: null,
    city: 'London',
    zip: 'NW1 5JD',
    countryId: 826,
  },
  shippingMethodId: 91,
})


Remove the coupon
await subbly.cart.update({ couponCode: null })

subbly.cart.addItem(payload, params?)

Adds a product, a plan or a bundle to the cart. Adding the same one-time item again raises its quantity instead of making a second line.

The payload has a shape per kind of item. All three share productId, quantity and metadata; the rest depends on what you are adding.

Method parameters

payloadRequiredCartItemAddPayload

The item to add.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart. The call rejects with code: 'out_of_stock' when the product ran out.


Add a one-time product
await subbly.cart.addItem({ productId: 3301, quantity: 2 })


Add a subscription with survey answers
await subbly.cart.addItem({
  productId: 8801,
  options: [
    { questionId: 11, answers: [{ id: 41 }] },
    { questionId: 12, answers: [{ content: 'No nuts, please' }] },
  ],
})


Add a bundle
await subbly.cart.addItem({
  productId: 8801,
  quantity: 1,
  bundle: {
    items: [
      { productId: 3301, quantity: 2 },
      { productId: 3307, quantity: 1 },
    ],
    preferences: [{ attributeId: 9, values: [31] }],
  },
})

subbly.cart.updateItem(cartItemId, payload, params?)

Changes one line in the cart: the quantity, the survey answers, the gift details or the bundle contents. To change which product a line is for, remove it and add the new one.

Method parameters

cartItemIdRequiredstring

UUID of the line, from cart.items[].id.

payloadRequiredCartResourceUpdateItemPayload

What to change. Every field is optional, and the shape follows the kind of item the line holds.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Change the quantity
const [line] = subbly.cart.items

await subbly.cart.updateItem(line.id, { quantity: 3 })

subbly.cart.removeItem(cartItemId, params?)

Removes one line from the cart.

Method parameters

cartItemIdRequiredstring

UUID of the line, from cart.items[].id.

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The updated cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Remove an item
const [line] = subbly.cart.items

await subbly.cart.removeItem(line.id)

subbly.cart.getStartDates()

Gets the dates on which the subscription in the cart can start. Send the one the customer picks to subbly.cart.update as startsAt.

It uses the cart the SDK holds, so load or create a cart first.

ReturnsPromise<CartResourceStartDatesResponse>

The dates allowed. The API fills one of the two fields and sets the other to null: a fixed list of dates, or an open range. Handle both.

availableDatesstring[] | null

The exact dates allowed, as ISO dates. null when the shop gives an open range instead.

range[string, string] | null

The earliest and the latest date allowed, as ISO dates. null when the shop lists exact dates instead.


Get the start dates
const { availableDates, range } = await subbly.cart.getStartDates()

const startsAt = availableDates?.length ? availableDates[0] : range?.[0]

await subbly.cart.update({ startsAt })

subbly.cart.getGiftingDates()

Gets the dates on which a gift subscription in the cart can start. Send the one the customer picks to subbly.cart.update as giftInfo.startsAt.

ReturnsPromise<CartResourceGiftingDatesResponse>

The dates allowed, in the same shape subbly.cart.getStartDates returns.

availableDatesstring[] | null

The exact dates allowed, as ISO dates. null when the shop gives an open range instead.

range[string, string] | null

The earliest and the latest date allowed, as ISO dates. null when the shop lists exact dates instead.


Get the gifting dates
const { availableDates, range } = await subbly.cart.getGiftingDates()

const startsAt = availableDates?.length ? availableDates[0] : range?.[0]

await subbly.cart.update({
  giftInfo: {
    startsAt,
    numberOfOrders: 3,
    message: 'Happy birthday',
    recipientEmail: 'grace@example.com',
  },
})

subbly.cart.getShippingMethods(params)

Gets the delivery options available for the cart at a destination. Send the ID of the one the customer picks to subbly.cart.update as shippingMethodId.

Only countryId and zip are needed. Pass the rest when a carrier quotes on the full address.

Method parameters

paramsRequiredCartShippingMethodsParams

Where the order is going.

countryIdRequirednumber

ID of the country, from subbly.countries.list(). The field is countryId, not country.

zipRequiredstring

Postal or ZIP code of the destination.

regionIdoptionalnumber

ID of the region, from the country's regions[].id.

firstNameoptionalstring

Given name of the recipient.

lastNameoptionalstring

Family name of the recipient.

phoneoptionalstring

Phone number of the recipient.

addressOneoptionalstring

First address line.

addressTwooptionalstring | null

Second address line.

cityoptionalstring

City.

expandoptionalstring[]

Relations to include: method and carrier.

ReturnsPromise<ShippingMethodDelivery[]>

The delivery options. Read type first: it is shipping_option for a carrier delivery and local_delivery for the shop's own, and it decides which of the fields below are set.


Get the shipping methods
const methods = await subbly.cart.getShippingMethods({
  countryId: 826,
  zip: 'NW1 5JD',
  expand: ['carrier'],
})

await subbly.cart.update({ shippingMethodId: methods[0].id })

subbly.cart.getLocalPickups()

Gets the pick-up points available for the cart. Send the ID of the one the customer picks to subbly.cart.update as shippingMethodId, along with pickupInfo for who collects the order.

ReturnsPromise<ShippingMethodPickup[]>

The pick-up points. The array is empty when the shop offers none.


Get the pick-up points
const points = await subbly.cart.getLocalPickups()

await subbly.cart.update({
  shippingMethodId: points[0].id,
  pickupInfo: {
    firstName: 'Ada',
    lastName: 'Lovelace',
    phone: '+442071234567',
  },
})

subbly.cart.attachCustomer(params?)

It needs a signed-in customer.

Method parameters

paramsoptionalCartResourceParams

Relations to include.

expandoptionalstring[]

The relations to fill in. The values are listed at the top of this page.

ReturnsPromise<CartModel>

The attached cart, which is subbly.cart itself. Its fields are written out under Create a cart.


Attach the customer after a log-in
await subbly.auth.login({ email, password })
await subbly.cart.attachCustomer({ expand: ['items.product'] })

Last modified on September 15, 2026