Opening checkout

Sorai.checkout({
  productId: "0199b0f0-0000-7000-8000-000000000021",
  priceId: "0199b0f0-0000-7000-8000-000000000031",
  quantity: 2,
});

priceId picks the currency: a product has one price per currency. Leave it off and the store's default currency is used. quantity defaults to 1.

The first time a tab opens checkout for a product, the runtime also sends an InitiateCheckout event for it.

Modal or full pageCopy Anchor Link

On a viewport 768px or wider, checkout opens in a modal over your page: a backdrop, a panel, and the checkout inside it with its own close button. Only that button closes it. Escape, a click on the backdrop and a finished payment all leave it open, so a buyer never loses a payment code or a receipt they are still reading. Your page stops scrolling while the modal is up, and focus returns to the control that opened it.

Below 768px the whole page goes to checkout instead. A phone has no room for a modal, and a framed checkout on a phone breaks the wallet apps a payment may hand off to.

Knowing when the buyer paidCopy Anchor Link

When a payment completes inside the modal, the runtime dispatches a sorai:paid event on window. The modal stays open on the receipt.

window.addEventListener("sorai:paid", () => {
  document.body.classList.add("thank-you");
});

The event is a signal for your page, such as showing a thank-you state. It is sent from the buyer's browser, so it is not proof of payment: confirm a sale from your server with webhooks before you deliver anything.

Hidden fieldsCopy Anchor Link

fields fills the store's hidden checkout fields, for tags of your own:

Sorai.checkout({
  productId: "0199b0f0-0000-7000-8000-000000000021",
  fields: { campaign: "spring" },
});

The values are saved on the order as custom_fields and come back in every order webhook. Keys that are not one of the store's hidden fields are dropped. Query parameters on the page's own URL are passed the same way, and fields wins when both name the same key.

The values come from the buyer's browser, so the buyer can change them. Never use them to decide whose account to credit: for that, create a checkout session from your server and send the buyer to its link.

UTM parameters need no hidden field. The runtime records them as attribution, and they arrive on the order with it.