Reference
Every method and type sorai-js exposes.
The runtime's whole public surface: the window.Sorai object and the types its methods take and return. The custom elements are described in Custom elements.
SoraiApi
window.Sorai: the runtime's whole JavaScript API.
Sorai.init()
Sorai.init(config: SoraiInitConfig): voidConfigures the runtime. Call it once, before anything else. It records first-touch attribution, loads the configured pixels and sends a PageView for the page named by window.SORAI_PAGE_ID.
Sorai.checkout()
Sorai.checkout(options: CheckoutOptions): voidOpens checkout for a product: in a modal over the page on a viewport 768px or wider, or by navigating to checkout on a narrower one. Sends InitiateCheckout once per product per tab session.
Sorai.track()
Sorai.track(name: string, props?: Record<string, unknown>): voidSends an event to Sorai and to every configured pixel. ViewContent and InitiateCheckout with a product_id prop are deduplicated per product; any other name is a custom event.
Sorai.product()
Sorai.product(id: string): Promise<SoraiProduct | null>Fetches one product with the publishable key. Resolves to null when the store has no active product with that id, and rejects when the request fails.
SoraiInitConfig
What Sorai.init() takes.
| Property | Type | Description |
|---|---|---|
storeId | string | The store's id. |
storeSlug? | string | The store's slug. When set, checkout links name the store by slug instead of by id. |
publicKey | string | The store's publishable key (spk_...). Safe in page source; never put a secret key here. |
apiBase | string | Base URL of the Sorai API, with no trailing slash. |
checkoutBase | string | Base URL of the Sorai checkout. |
currency? | string | The store's default currency (ISO 4217). <sorai-price> renders the price row matching it unless the element overrides with a currency attribute. Omitted, the element falls back to the product's first price row. |
locale? | string | The store's locale, used to format prices. Omitted, the browser's wins. |
pixels? | PixelsConfig | The ad and analytics tags to load. |
PixelsConfig
Ad and analytics tags the runtime loads and forwards every event to.
| Property | Type | Description |
|---|---|---|
metaPixelId? | string | Meta Pixel id. |
tiktokPixelId? | string | TikTok Pixel id. |
ga4Id? | string | Google Analytics 4 measurement id, such as G-ABC123. |
gtmId? | string | Google Tag Manager container id, such as GTM-XXXX. |
CheckoutOptions
What Sorai.checkout() takes.
| Property | Type | Description |
|---|---|---|
productId | string | The product to buy. |
priceId? | string | The price to charge, which picks the currency. Omitted, the store's default currency is used. |
quantity? | number | How many to buy. Default: 1. |
fields? | Record<string, string> | Values for the store's hidden checkout fields, keyed by field key, such as { campaign: "spring" }. They come back in the order's custom_fields; keys the form does not have are dropped. The buyer can change them, so never use them to identify a user: open a checkout session from your server for that. |
SoraiProduct
A product as Sorai.product() returns it. The fields below are always there; any other field the API returns comes through as it is.
| Property | Type | Description |
|---|---|---|
id | string | The product id. |
slug | string | The product's slug, the last segment of its page URL. |
name | string | The product's name. |
description | string | The product's description. |
prices | SoraiPrice[] | One price per currency the product sells in. |
SoraiPrice
One price of a product. A product has one price per currency, and Sorai never converts between them.
| Property | Type | Description |
|---|---|---|
id | string | The price id, to pass as priceId to Sorai.checkout(). |
currency | string | ISO 4217 currency code. |
amount_minor | number | The amount in the currency's minor units: 149000 in IDR is Rp 149.000, 1900 in USD is $19.00. |
kind? | string | one_time or recurring. |
pay_what_you_want? | boolean | True when the buyer chooses what to pay. |
min_minor? | number | null | The lowest amount a buyer may pay, in minor units, when pay_what_you_want is true. |