cart

Add, update and remove cart items, apply coupons, place a quick order and send the customer to checkout.

Use Salla.cart for everything the customer does to the cart in the browser. To show a cart on a page, read it with the cart API module or the cart route.

app/components/product/QuantityAdd.tsx
export function QuantityAdd({ productId }: { productId: number }) {
  async function add(quantity: number) {
    await window.salla?.cart.addItem({ id: productId, quantity, notes: 'Gift wrap please' });
  }
  return <button onClick={() => add(2)}>Add two</button>;
}

You never pass a cart id. The SDK finds the customer's current cart, and creates one on the first add.

Items

MethodParametersDoes
addItemid or { id, quantity?, options?, notes? }Adds a product. Without quantity it uses the quick-add request.
quickAddid, quantity?Adds a product from a list, without opening its page
updateItem{ id, quantity?, options? } or FormDataChanges a cart item. id is the cart item id.
deleteItemitemId or { id }Removes a cart item
deleteImagefileId or { id }Removes an image the customer uploaded for an item

options maps each option id to the chosen value: the value id for a choice, a URL for an uploaded image, or the text for a text field.

Salla.cart.addItem({
  id: 1234,
  quantity: 1,
  options: { 117414452: 11232214, 117411132: 'Name on the cup' },
});

Coupons

MethodParametersDoes
addCouponcode or { coupon }Applies a coupon
deleteCouponcode?Removes the coupon. On a store that allows several, pass the code to remove only that one.

The useCoupon hook wraps both, with loading and error state.

Read the cart

MethodParametersReturns
detailscartId?, with?The cart with its items. with can be ['options', 'attachments'] for more item data.
getCurrentCartIdnoneA promise of the current cart id
latestnoneThe customer's latest cart, created if there is none
statuscartId?Whether the cart is active and its next step (checkout, login or refresh)
offersnoneThe offers that apply to the cart
getUploadImageEndpointcartId?The URL to upload an item image to. A string, not a request.

Checkout and quick order

MethodParametersDoes
submitnoneSends the customer on: to checkout, or to log in first when the store needs it
getQuickOrderSettingsnoneReads the store's quick-order form settings
createQuickOrder{ name, email?, phone, country_code, product_ids, agreement }Places an order without the usual checkout steps
priceQuotecartId?Asks the store for a price quote. A guest is asked to log in first.
resetnoneForgets the saved cart in the browser, so the next call loads a fresh one

Events

EventFires whenArguments
cart::updatedThe cart changed by any method abovethe cart summary (count, total, sub_total, discount and more)
cart::before.add.itemBefore an add is sent{ id, payload }, which you can change
cart::item.added / cart::item.added.failedaddItem, quickAddresponse or error, product id
cart::item.updated / cart::item.updated.failedupdateItemresponse or error, item id
cart::item.deleted / cart::item.deleted.faileddeleteItemresponse or error, item id
cart::image.deleted / cart::image.not.deleteddeleteImageresponse or error, file id
cart::coupon.added / cart::coupon.addition.failedaddCouponresponse or error, cart id
cart::coupon.deleted / cart::coupon.deletion.faileddeleteCouponresponse or error, cart id
cart::details.fetched / cart::details.not.fetcheddetailsresponse or error
cart::latest.fetched / cart::latest.failedlatestresponse or error
cart::offers.fetched / cart::offers.failedoffersresponse or error
cart::submittingBefore submit checks the cartnone
cart::submitted / cart::submit.failedsubmitresponse or error
cart::quick-order.fetchedgetQuickOrderSettings workedresponse
cart::quick-order.succeededcreateQuickOrder workedresponse
cart::quick-order.failedEither quick-order call failederror
cart::price-quote.succeeded / cart::price-quote.failedpriceQuoteresponse or error
cart::success.resetresetnone

Listen to cart::updated to keep a cart badge or summary in step. See React to cart events.

Gotchas

  • updateItem and deleteItem take the cart item id (item.id in the cart), not the product id.
  • Calls to updateItem for the same item are sent one at a time, in order. Rapid quantity clicks do not overtake each other.
  • addItem with quantity checks the option fields on the current product page first. If one is missing, the browser points at it and the add fails.
  • When an add fails for a reason other than invalid data, the SDK resets the cart and tries once more.
  • details and offers reject with a CartNotCreated error for a guest who has not added anything yet. Show an empty cart then.
  • submit and a successful priceQuote leave the page: to checkout, to login, or back to the home page.

See also

On this page