shoply.js reference - Shoply Documentation

Everything hangs off the global shoply, after init(). Calls that ask the server answer a promise of the 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 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 and the Checkout Kit send shoply:paid on window when an order is paid on your page.

​Starting

​Reading the store

​The basket

​Offers

​Checking out

​Prices

​Helpers

​Events on your own site