Overview

What the Salla SDK is, how your theme gets it, and when to use it instead of the API client.

Read this before you call the SDK. It explains what it is, when to reach for it, and the rules that apply to every module in this tab.

The Salla SDK is a script the engine loads in the browser. It talks to the store for the customer: it adds to the cart, logs in, rates an order, changes the currency. In code it is the global window.salla (also window.Salla). In prose we call it Salla.

You do not set it up

The engine adds the SDK to every page and starts it with the store, theme and customer data. You never install it or call Salla.init() yourself.

The SDK only exists in the browser. On the server there is no window, so follow the rules in Salla SDK and events: call it from event handlers or useEffect, never while rendering.

SDK or API client

The engine gives you two ways to talk to the store. They do different jobs.

UseWhenExample
API clientRead data for a page, on the server or in the browserproduct.find(id) in a loader
SDKChange something for the customer, in the browserSalla.cart.addItem(id) on a click

Check the hooks first too. useWishlist, useProduct and useCoupon already call the SDK for you and keep the page in sync.

Call a method

Every module hangs off the global: Salla.cart, Salla.wishlist, Salla.auth and so on. Methods return a promise.

app/components/product/AddButton.tsx
export function AddButton({ productId }: { productId: number }) {
  async function add() {
    try {
      await window.salla?.cart.addItem({ id: productId, quantity: 1 });
    } catch {
      // the SDK already showed the error message
    }
  }

  return <button onClick={add}>Add to cart</button>;
}

What comes back

A successful call resolves with the response body:

{ "status": 200, "success": true, "data": { "cart": { "id": 123, "count": 2 } } }

A failed call rejects. A server error rejects with the request error, and its body is in error.response.data. When the SDK rejects a call before sending it (a missing id, for example), it rejects with a plain message string.

Messages are shown for you

When the response carries a message, the SDK shows it to the customer, for example after a coupon is applied or rejected. The engine routes these messages to its toast, so do not show a second one yourself. To call a method without any message, wrap it: await Salla.api.withoutNotifier(() => Salla.cart.details()). See Notify.

Each method fires events

Every method also announces its result as an event, such as cart::item.added or cart::item.added.failed. That is how other parts of the page (the cart badge, a toast, an app) stay in sync. See Events.

Modules

ModuleDoes
cartAdd, update and remove items, coupons, quick order, checkout
productPrice for chosen options, search, lists, offers, gifting, size guides
wishlistAdd, remove, toggle and share
bookingBook a product that is a service
authLog in with a code, register, log out
profileUpdate the customer's details and contacts
orderCancel, reorder, send the invoice, list orders
ratingRate the store, products and shipping of an order
commentAdd and list comments on products, pages and articles
loyaltyRead the program, exchange points for a prize
currencyList and change the currency
componentMenus and reviews for header, footer and home blocks
metadataCustom field values for products and other entities

The shared parts: Config, Storage, Helpers, Notify, Forms and Languages.

Gotchas

  • Wait for the SDK before you call it. await Salla.onReady() resolves once it has started, and it is safe to call at any time.
  • Many methods also take a FormData or a plain object with the same fields, so a form can pass its data as is. See Forms.
  • The salla-* web components already call these methods. Check the web components before you build a feature by hand.

See also

On this page