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



Use `Salla.product` for product actions in the browser. To load products for a page, use the [`product` API module](https://docs.salla.dev/twilight/react/api/modules/product) in a loader instead.

The product page's price updates through this module: when an option changes, `getPrice` asks the store for the new price.
The [`useProduct`](https://docs.salla.dev/twilight/react/hooks/use-product) hook listens to the result, so most themes never call it directly.

```ts
// the price for the options the customer picked
const { data } = await Salla.product.getPrice({
  id: 1234,
  quantity: 2,
  options: { 117414452: 11232214 },
});
```

## Price and details [#price-and-details]

| Method          | Parameters                                  | Returns                                                                                   |
| --------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `getPrice`      | `{ id, quantity?, options? }` or `FormData` | The price for that quantity and those options                                             |
| `getDetails`    | `id, with?`                                 | The product. `with` adds related data, such as `['images', 'sold_quantity', 'category']`. |
| `getSizeGuides` | `id`                                        | The product's size guides                                                                 |
| `offers`        | `id`                                        | The special offers on the product                                                         |

## Lists and search [#lists-and-search]

| Method         | Parameters                       | Returns                                                      |
| -------------- | -------------------------------- | ------------------------------------------------------------ |
| `fetch`        | `{ source, source_value?, ... }` | A list of products. See the sources below.                   |
| `search`       | `query` or `{ query, ... }`      | Products that match the text                                 |
| `categories`   | `id?`                            | The product categories, or one category when you pass its id |
| `fetchOptions` | `ids, { with? }`                 | The options of several products at once                      |

`fetch` takes a `source` and, for most sources, a `source_value`:

| `source`                                                        | `source_value`  |
| --------------------------------------------------------------- | --------------- |
| `categories`, `brands`, `tags`, `selected`                      | An array of ids |
| `search`                                                        | The search text |
| `related`                                                       | One product id  |
| `offers`, `latest`, `sales`, `wishlist`, `top-rated`, `reorder` | None            |

```ts
const { data } = await Salla.product.fetch({ source: 'categories', source_value: [12, 15] });
```

## Back in stock [#back-in-stock]

| Method                       | Parameters                                                  | Does                                                                                   |
| ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `availabilitySubscribe`      | `id`, or `{ id, email }`, or `{ id, country_code, mobile }` | Asks to tell the customer when the product is back. A guest passes an email or mobile. |
| `isSubscribedToAvailability` | `id`                                                        | `true` when this browser already subscribed. No request.                               |
| `getAvailabilityChannels`    | none                                                        | The channels the store uses: `'email'`, `'sms'` or both, comma-separated               |

## Gifting [#gifting]

| Method                  | Parameters                   | Does                                                                                  |
| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------- |
| `getGiftProductDetails` | `id`                         | The gift options of a product: images and texts the customer can choose               |
| `uploadGiftImage`       | `FormData`                   | Uploads an image for the gift card                                                    |
| `addProductGiftToCart`  | `id, payload, withRedirect?` | Adds the product as a gift. With `withRedirect`, goes to the address in the response. |

## Events [#events]

| Event                                                                         | Fires when                                             | Arguments                     |
| ----------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------- |
| `product::price.updated` / `product::price.updated.failed`                    | `getPrice`                                             | response or error, product id |
| `product::detail.fetched` / `product::detail.failed`                          | `getDetails`                                           | response or error, product id |
| `product::size-guide.fetched` / `product::size-guide.failed`                  | `getSizeGuides`                                        | response or error, product id |
| `product::offers.fetched` / `product::fetch.offers.failed`                    | `offers`                                               | response or error, product id |
| `product::offer.existed`                                                      | A cart response carries an offer for the added product | the offer                     |
| `product::fetch.succeeded` / `product::fetch.failed`                          | `fetch`                                                | response or error             |
| `product::search.results` / `product::search.failed`                          | `search`                                               | response or error, query      |
| `product::categories.fetched` / `product::categories.failed`                  | `categories`                                           | response or error             |
| `product::options.fetched` / `product::options.not.fetched`                   | `fetchOptions`                                         | response or error             |
| `product::availability.subscribed` / `product::availability.subscribe.failed` | `availabilitySubscribe`                                | response or error, product id |
| `product::gift.fetched` / `product::gift.failed`                              | `getGiftProductDetails`                                | response or error, product id |
| `product::gift.image-upload.succeeded` / `product::gift.image-upload.failed`  | `uploadGiftImage`                                      | response or error             |
| `product::gift.add-to-cart.succeeded` / `product::gift.add-to-cart.failed`    | `addProductGiftToCart`                                 | response or error, product id |

## Gotchas [#gotchas]

* `search` rejects a query that is the same as the one before it, so a double submit sends one request.
* `fetch` checks `source_value` before sending: a missing array for `categories` or a non-number for `related` rejects at once.
* `fetch` shows no messages, even on failure. Handle the rejected promise.
* Pass `offers` the id as a number. An object such as `{ id }` is not read and the call fails.
* When `getDetails` fails on the server, the SDK fires `product::availability.subscribe.failed`, not `detail.failed`. Handle the promise instead of the event.

## See also [#see-also]

* [`product` API module](https://docs.salla.dev/twilight/react/api/modules/product)
* [`useProduct`](https://docs.salla.dev/twilight/react/hooks/use-product)
* [Product route](https://docs.salla.dev/twilight/react/routes/product)
* [Events](https://docs.salla.dev/twilight/react/sdk/events)
