Elements reference

ShopFast(), elements(), every element and its options, element and group methods, and confirmPayment().

Types for all of this are in shopfast-elements.d.ts. Save it next to your code and reference it with /// <reference path="shopfast-elements.d.ts" />, or copy the parts you use.

ShopFast()

const shopfast = ShopFast({ store: "https://lumenfold.shopfa.st", nonce: "r4nd0m", debug: false });

Option	What it does
`store`	Your store’s address. Leave it out when the script loads from your store. A custom domain works too.
`nonce`	Your CSP nonce. Put on every frame and style tag the script adds. See Content Security Policy.
`debug`	Logs every event to the console while you build.

ShopFast("https://lumenfold.shopfa.st") works too. shopfast.version is the script’s version.

shopfast.elements()

One shared cart and the elements that show it. Make one per checkout on the page.

const elements = shopfast.elements({
  items: [
    { product: "northwind-sans", variant: "var_9zp0phmv1xa45v7g97wv", quantity: 1 },
    { product: "studio-notion-templates", amount: "12.00" },
  ],
  brand: { mode: "light", tokens: { accent: "#b2452a" } },
  locale: "de",
  returnUrl: "https://yourshop.com/thanks",
});

Option	What it does
`items`	What starts in the cart, up to 20 lines. `product` is a handle or a `prd_` id; `variant` an option’s `var_` id (the first available option when left out); `quantity` 1 to 100; `amount` the price for pay what you want products, as the buyer would type it. Leave it empty to let `product` and `buyButton` elements fill the cart.
`brand`	`mode`, `preset`, `tokens`, `fonts` and `rules`. See Styling.
`locale`	Language and number format, like `de` or `fr-CA`. Built-in words come in English, German, French and Spanish; prices format for any locale. Defaults to your page’s `lang`.
`strings`	Replace any built-in word by key, like `{ addToCart: "Get it" }`. Your checkout’s own words (pay button, headings, terms) come from Storefront → Checkout.
`returnUrl`	Where a gateway that takes over the whole tab sends the buyer back to. See Taking payment.
`currency`	The store always charges in its own currency. If you pass a different one, a `trace` says which one is used.

elements.create()

elements.create(type, options) returns an element. Nothing shows until you mount it.

checkout

Everything in one element.

Option	Default	What it does
`showSummary`	`true`	The cart lines and add-ons above the form. `false` shows just the total.
`title`	none	A title row with “Secure checkout”. The overlay checkout uses your store’s name here.

summary

Option	Default	What it does
`editable`	`true`	Quantity steppers and remove. `false` shows quantities only.
`showOffers`	`true`	Order bumps and upsells under the lines.
`showCodes`	`false`	A code field inside the summary, for layouts without a `coupon` element.
`showProgress`	`true`	The reward bar (“$6.00 to go: free bonus pack”), when your store has one.

email

Option	Default	What it does
`label`	“Email”	The field’s label.
`placeholder`	“[email protected]”	The field’s placeholder.

When Fraud Shield asks the buyer to confirm their email, the 6-digit code box opens in this element.

payment

Option	Default	What it does
`layout`	`list`	`grid` puts the ways to pay side by side.

Shows the store’s ways to pay for the buyer’s country and order total (your rules and order limits apply, with the reason when one is not offered). In test mode the selected way shows the test card and the test outcomes.

coupon

Option	Default	What it does
`collapsed`	`false`	Starts as a “Have a code?” link.

Takes discount codes and gift card codes in one field. Applied codes show as chips with a remove button.

Option	Default	What it does
`showSeller`	`true`	“Sold by”, with your legal details from Settings → General.

Shows your terms checkbox, the marketing opt-in when you turned it on, and the EU and UK immediate delivery box for buyers who need it, with the same sentence and rules as your own checkout.

billingAddress

No options. Shows name, country, phone and address as Storefront → Checkout → Fields asks for them. When every field is hidden it draws nothing.

customFields

No options. Your checkout questions and the questions of the products in the cart.

payButton

No options. The pay button with the total (or “Confirm and continue” while an email code is pending), your secure checkout note and trust badges. Alone on the page, without a checkout or payment element, it also shows the messages the buyer needs and the paid state.

product

Option	Default	What it does
`product`	required	A handle or `prd_` id.
`variant`	first available	The option picked at first.
`layout`	`card`	`compact` or `row`.
`showDescription`	`true`	The short description.
`showQuantity`	`false`	A quantity stepper; quantity prices update as it changes.
`showTiers`	`true`	Quantity prices (“Buy 5+ · save 20%”).
`action`	`add`	`buy` adds the product and opens the checkout overlay.
`text`	“Add to cart”	The button label.

buyButton

Option	Default	What it does
`product`	required	A handle or `prd_` id.
`variant`, `quantity`		What it adds. Nothing is added twice: a product already in the cart just opens the overlay.
`text`	“Buy now”	The label.
`showPrice`	`true`	The price after the label.
`size`	`md`	`sm`, `md` or `lg`.
`block`	`false`	Full width.

cartButton

Option	Default	What it does
`text`	“Cart”	The label.
`showTotal`	`false`	The total next to the count.
`size`, `block`		As for `buyButton`.

tip and offers

tip shows your tip amounts (Storefront → Checkout → Tips) and draws nothing when your store takes none. offers shows order bumps, upsells and the reward bar; pass title to give it a heading.

Element methods

Method	What it does
`mount(target)`	Put the element in the page: a CSS selector or an element.
`update(options)`	Change its options without remounting.
`focus()`	Focus its first field.
`unmount()`	Take it out of the page; `mount` puts it back with the same cart.
`destroy()`	Remove it for good.
`on(event, handler)`	Listen to this element’s own `ready`, `change`, `focus`, `blur`, `resize` and `loaderror`.

Group methods

Method	What it does
`on(event, handler)`	Listen to an event from any element, or to all of them with `'*'`. Returns a function that stops listening. Handlers get `(data, eventName)`.
`once(event, handler)`	Listen once.
`off(event, handler)`	Stop listening.
`update({ brand, items, locale, strings, returnUrl })`	Restyle, re-word or replace the cart in place. No remount, no flash.
`addItem(item)`	Put products in the cart from your own buttons. Takes one item or a list.
`edit()`	Unlock the form after a payment was started, to fix a typo or pick another way to pay.
`open()`, `close()`	Open or close the checkout overlay the buy and cart buttons use.
`getElement(type)`	The first element of a type, or `null`.
`destroy()`	Remove every frame and listener.

shopfast.confirmPayment()

Pay from your own button instead of the payButton or checkout element:

payButton.addEventListener("click", async () => {
  const result = await shopfast.confirmPayment({ elements, returnUrl: "https://yourshop.com/thanks" });
  if (result.error) showMessage(result.error.message);
  else showThanks(result.order.number);
});

It resolves once the order is paid ({ order }) or the payment stopped ({ error }). Call it from the click itself: some gateways need their own window, and browsers only let a page open one during a click. Details in Taking payment.