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.
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
| Method | Parameters | Does |
|---|---|---|
addItem | id or { id, quantity?, options?, notes? } | Adds a product. Without quantity it uses the quick-add request. |
quickAdd | id, quantity? | Adds a product from a list, without opening its page |
updateItem | { id, quantity?, options? } or FormData | Changes a cart item. id is the cart item id. |
deleteItem | itemId or { id } | Removes a cart item |
deleteImage | fileId 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
| Method | Parameters | Does |
|---|---|---|
addCoupon | code or { coupon } | Applies a coupon |
deleteCoupon | code? | 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
| Method | Parameters | Returns |
|---|---|---|
details | cartId?, with? | The cart with its items. with can be ['options', 'attachments'] for more item data. |
getCurrentCartId | none | A promise of the current cart id |
latest | none | The customer's latest cart, created if there is none |
status | cartId? | Whether the cart is active and its next step (checkout, login or refresh) |
offers | none | The offers that apply to the cart |
getUploadImageEndpoint | cartId? | The URL to upload an item image to. A string, not a request. |
Checkout and quick order
| Method | Parameters | Does |
|---|---|---|
submit | none | Sends the customer on: to checkout, or to log in first when the store needs it |
getQuickOrderSettings | none | Reads the store's quick-order form settings |
createQuickOrder | { name, email?, phone, country_code, product_ids, agreement } | Places an order without the usual checkout steps |
priceQuote | cartId? | Asks the store for a price quote. A guest is asked to log in first. |
reset | none | Forgets the saved cart in the browser, so the next call loads a fresh one |
Events
| Event | Fires when | Arguments |
|---|---|---|
cart::updated | The cart changed by any method above | the cart summary (count, total, sub_total, discount and more) |
cart::before.add.item | Before an add is sent | { id, payload }, which you can change |
cart::item.added / cart::item.added.failed | addItem, quickAdd | response or error, product id |
cart::item.updated / cart::item.updated.failed | updateItem | response or error, item id |
cart::item.deleted / cart::item.deleted.failed | deleteItem | response or error, item id |
cart::image.deleted / cart::image.not.deleted | deleteImage | response or error, file id |
cart::coupon.added / cart::coupon.addition.failed | addCoupon | response or error, cart id |
cart::coupon.deleted / cart::coupon.deletion.failed | deleteCoupon | response or error, cart id |
cart::details.fetched / cart::details.not.fetched | details | response or error |
cart::latest.fetched / cart::latest.failed | latest | response or error |
cart::offers.fetched / cart::offers.failed | offers | response or error |
cart::submitting | Before submit checks the cart | none |
cart::submitted / cart::submit.failed | submit | response or error |
cart::quick-order.fetched | getQuickOrderSettings worked | response |
cart::quick-order.succeeded | createQuickOrder worked | response |
cart::quick-order.failed | Either quick-order call failed | error |
cart::price-quote.succeeded / cart::price-quote.failed | priceQuote | response or error |
cart::success.reset | reset | none |
Listen to cart::updated to keep a cart badge or summary in step. See React to cart events.
Gotchas
updateItemanddeleteItemtake the cart item id (item.idin the cart), not the product id.- Calls to
updateItemfor the same item are sent one at a time, in order. Rapid quantity clicks do not overtake each other. addItemwithquantitychecks 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.
detailsandoffersreject with aCartNotCreatederror for a guest who has not added anything yet. Show an empty cart then.submitand a successfulpriceQuoteleave the page: to checkout, to login, or back to the home page.