> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoply.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# shoply.js reference

> Every call of shoply.js

Everything hangs off the global `shoply`, after `init()`. Calls that ask the server answer a promise of the [envelope](/sdk/introduction.md#every-answer-is-an-envelope).

## Starting

| Call | What it does |
| - | - |
| `init(storeId, options?)` | Start the script for a store, by its ID or its name. Call it once, before anything else. |

`options` may hold `adaptivePricing: false`, to be handed the store's own prices and not the buyer's, and `timeout`, in milliseconds, for how long to wait for an answer (20 seconds unless set).

## Reading the store

| Call | What it does |
| - | - |
| `getStore()` | The store: its name, branding, currency, products and running sales. Kept, and calls made at the same time share one request. |
| `getProducts()` | The store's products. |
| `getCategories()` | Its categories. |
| `getProduct(idOrSlug)` | One product, by its ID or the last part of its address. It carries its add-ons (`addons`) and what is bought together with it (`together`). |

## The basket

Kept in the browser, for each store, so two stores open in one browser never share a cart.

| Call | What it does |
| - | - |
| `getBasket()` | What is in it. |
| `addToBasket(productId, variantId, quantity, options?)` | Add to it. The same variant twice is one line. `options.addons` is the IDs of the add-ons ticked beside it, and `options.offer` the offer it was taken through. |
| `setQuantity(productId, variantId, quantity, offer?)` | Change a line. `0` removes it. |
| `setAddons(productId, variantId, addons)` | Set the add-ons ticked for a line. An empty list unticks them all. |
| `removeFromBasket(productId, variantId, offer?)` | Remove a line. |
| `clearBasket()` | Empty it. |
| `basketCount()` | How many items are in it. |
| `basketSubtotal()` | What it comes to. |

### Offers

What the store sets on its [Upselling](/guides/upselling.md) page. The checkout prices every offer again, so what the basket shows is a guide.

| Call | What it does |
| - | - |
| `cartOffers()` | What the store offers beside the basket as it is: products offered in the cart (`kind` `cart`) and upgrades for its lines (`upgrade`). Also brings each taken offer's price in line with what the checkout will charge. |
| `takeOffer(offer)` | Put one of those offers in the basket: a cart offer as a line of one, an upgrade in place of the line it is for. |
| `offersSeen(ids)` | Tell the store which offers a page showed, for the figures on its Upselling page. |

## Checking out

| Call | What it does |
| - | - |
| `checkout(email, coupon?)` | Send the buyer to the checkout with the basket. The email is needed. The buyer can still change it there. |
| `createOrder(email, productId, variantId, quantity?, options?)` | The checkout for one item, for a Buy now button. `options.addons` names its ticked add-ons. |
| `validateCoupon(code, subtotal?)` | What a coupon would take off. A preview only: the checkout checks it again. |
| `settleCheckout()` | Empty the basket once its checkout is paid. `init()` calls it for you. |

## Prices

| Call | What it does |
| - | - |
| `getPricing()` | The currency prices are shown in: the buyer's, with adaptive pricing on. |
| `formatPrice(amount)` | An amount written in that currency, the way the buyer's country writes it. A promise. |
| `createFormatter()` | A formatter for that currency, to format many prices with. |
| `lowestPrice(product)` | A product's cheapest variant. |
| `onSale(product)` / `activeSale()` | Whether a product is on sale, and the sale that is running. |
| `renews(variant)` | How often a variant sold by subscription renews, `{ every, unit }`, or null for one sold once. Since 1.26.0. |

## Helpers

| Call | What it does |
| - | - |
| `imageUrl(name)` | The address of one of the store's pictures. |
| `parseMetadata(product)` | A product's metadata, read from its JSON. |
| `visit()` | The visit this page is counted as. The embed and the Checkout Kit read it so that an order says where it came from. |
| `version` | The script's version. |

## Events on your own site

The [embed](/guides/embeds.md) and the [Checkout Kit](/guides/checkout-kit.md) send `shoply:paid` on `window` when an order is paid on your page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.