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.
| Use | When | Example |
|---|---|---|
| API client | Read data for a page, on the server or in the browser | product.find(id) in a loader |
| SDK | Change something for the customer, in the browser | Salla.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.
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
| Module | Does |
|---|---|
cart | Add, update and remove items, coupons, quick order, checkout |
product | Price for chosen options, search, lists, offers, gifting, size guides |
wishlist | Add, remove, toggle and share |
booking | Book a product that is a service |
auth | Log in with a code, register, log out |
profile | Update the customer's details and contacts |
order | Cancel, reorder, send the invoice, list orders |
rating | Rate the store, products and shipping of an order |
comment | Add and list comments on products, pages and articles |
loyalty | Read the program, exchange points for a prize |
currency | List and change the currency |
component | Menus and reviews for header, footer and home blocks |
metadata | Custom 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
FormDataor 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.