# Overview (https://docs.salla.dev/twilight/react/sdk)



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 [#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](https://docs.salla.dev/twilight/react/guide/salla-sdk-and-events): call it from event handlers or `useEffect`, never while rendering.

## SDK or API client [#sdk-or-api-client]

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

| Use                | When                                                  | Example                             |
| ------------------ | ----------------------------------------------------- | ----------------------------------- |
| [API client](https://docs.salla.dev/twilight/react/api) | 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](https://docs.salla.dev/twilight/react/hooks/use-store) first too. [`useWishlist`](https://docs.salla.dev/twilight/react/hooks/use-wishlist), [`useProduct`](https://docs.salla.dev/twilight/react/hooks/use-product) and [`useCoupon`](https://docs.salla.dev/twilight/react/hooks/use-coupon) already call the SDK for you and keep the page in sync.

## Call a method [#call-a-method]

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

```tsx title="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 [#what-comes-back]

A successful call resolves with the response body:

```json
{ "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 [#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](https://docs.salla.dev/twilight/react/components/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](https://docs.salla.dev/twilight/react/sdk/notify).

### Each method fires events [#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](https://docs.salla.dev/twilight/react/sdk/events).

## Modules [#modules]

| Module                        | Does                                                                  |
| ----------------------------- | --------------------------------------------------------------------- |
| [`cart`](https://docs.salla.dev/twilight/react/sdk/cart)           | Add, update and remove items, coupons, quick order, checkout          |
| [`product`](https://docs.salla.dev/twilight/react/sdk/product)     | Price for chosen options, search, lists, offers, gifting, size guides |
| [`wishlist`](https://docs.salla.dev/twilight/react/sdk/wishlist)   | Add, remove, toggle and share                                         |
| [`booking`](https://docs.salla.dev/twilight/react/sdk/booking)     | Book a product that is a service                                      |
| [`auth`](https://docs.salla.dev/twilight/react/sdk/auth)           | Log in with a code, register, log out                                 |
| [`profile`](https://docs.salla.dev/twilight/react/sdk/profile)     | Update the customer's details and contacts                            |
| [`order`](https://docs.salla.dev/twilight/react/sdk/order)         | Cancel, reorder, send the invoice, list orders                        |
| [`rating`](https://docs.salla.dev/twilight/react/sdk/rating)       | Rate the store, products and shipping of an order                     |
| [`comment`](https://docs.salla.dev/twilight/react/sdk/comment)     | Add and list comments on products, pages and articles                 |
| [`loyalty`](https://docs.salla.dev/twilight/react/sdk/loyalty)     | Read the program, exchange points for a prize                         |
| [`currency`](https://docs.salla.dev/twilight/react/sdk/currency)   | List and change the currency                                          |
| [`component`](https://docs.salla.dev/twilight/react/sdk/component) | Menus and reviews for header, footer and home blocks                  |
| [`metadata`](https://docs.salla.dev/twilight/react/sdk/metadata)   | Custom field values for products and other entities                   |

The shared parts: [Config](https://docs.salla.dev/twilight/react/sdk/config), [Storage](https://docs.salla.dev/twilight/react/sdk/storage), [Helpers](https://docs.salla.dev/twilight/react/sdk/helpers), [Notify](https://docs.salla.dev/twilight/react/sdk/notify), [Forms](https://docs.salla.dev/twilight/react/sdk/forms) and [Languages](https://docs.salla.dev/twilight/react/sdk/languages).

## Gotchas [#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](https://docs.salla.dev/twilight/react/sdk/forms).
* The `salla-*` web components already call these methods. Check the [web components](https://docs.salla.dev/twilight/react/web-components) before you build a feature by hand.

## See also [#see-also]

* [Salla SDK and events](https://docs.salla.dev/twilight/react/guide/salla-sdk-and-events)
* [Events](https://docs.salla.dev/twilight/react/sdk/events)
* [API client](https://docs.salla.dev/twilight/react/api)
