> ## Documentation Index > Fetch the complete documentation index at: https://quickbutik.dev/llms.txt > Use this file to discover all available pages before exploring further. # @quickbutik/kit > Generated type reference for the root entry point of @quickbutik/kit 1.8.0: the client, resources, types, storage, images, money, SEO and the variant matrix. Generated from the typings of `@quickbutik/kit@1.8.0` as published on npm. Do not edit this page by hand: run `npm run generate` in `tools/kit-api-reference`. For guided, example-led documentation see the [API reference](/kit/reference/client). ```ts theme={null} import { … } from "@quickbutik/kit" ``` ## Classes ### Analytics The hub: one `track()` the storefront calls, fanned out to every destination the shopper's consent allows. Events are remembered (bounded) rather than dropped when a destination is not ready for them: before the shopper decides, a `view_item` waits, and is delivered the moment `marketing` is granted — or forgotten the moment it is denied. The same memory covers destinations that arrive late, which is the normal case: `destinationsFromShop()` needs one request to learn the merchant's ids, and the product page's `view_item` has usually fired by then. Gating happens at dispatch time, so withdrawing consent stops a destination immediately even though its script stays on the page. Purchases are deduplicated across page loads through the platform's own localStorage key, and carried to destinations with the platform's own Meta `eventID`, so a thank-you page can be reloaded without counting the order twice — and the platform's server-side event, when there is one, merges with the browser's. #### Constructors ##### Constructor ```ts theme={null} new Analytics(options?): Analytics; ``` ###### Parameters | Parameter | Type | | - | - | | `options?` | [`AnalyticsOptions`](#analyticsoptions) | ###### Returns [`Analytics`](#analytics) #### Properties ##### requireConsent ```ts theme={null} readonly requireConsent: boolean; ``` False when the hub runs ungated (`requireConsent: false`). #### Accessors ##### consentState ###### Get Signature ```ts theme={null} get consentState(): ConsentState | null; ``` The decision the hub gates on; null when it runs ungated. Required consent with no store to read it from is an undecided shopper, forever — never null, which every destination reads as "everything granted". ###### Returns [`ConsentState`](#consentstate-1) | `null` ##### destinations ###### Get Signature ```ts theme={null} get destinations(): readonly AnalyticsDestination[]; ``` The destinations the hub holds, in order. ###### Returns readonly [`AnalyticsDestination`](#analyticsdestination)\[] #### Methods ##### addDestination() ```ts theme={null} addDestination(destination): void; ``` Add a destination after construction — what `destinationsFromShop()` feeds in once the shop's ids are known. It receives the events the hub still remembers, consent permitting. ###### Parameters | Parameter | Type | | - | - | | `destination` | [`AnalyticsDestination`](#analyticsdestination) | ###### Returns `void` ##### allows() ```ts theme={null} allows(category): boolean; ``` Whether a category may be used right now, by the hub's own rule. ###### Parameters | Parameter | Type | | - | - | | `category` | [`ConsentCategory`](#consentcategory) \| `null` | ###### Returns `boolean` ##### attachCart() ```ts theme={null} attachCart(cartStore): () => void; ``` Turn the cart store's mutations into `add_to_cart` / `remove_from_cart` events — the quantities that changed, not the whole basket — and learn the shop's currency and numeric store id from it. Both are kept once seen: a cart that goes away (bought, expired) does not unlearn the shop. Returns the detach function. ###### Parameters | Parameter | Type | | - | - | | `cartStore` | [`CartStore`](/kit/api/react#cartstore) | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` ##### destroy() ```ts theme={null} destroy(): void; ``` `stop()`, plus forget the cart and the remembered events. ###### Returns `void` ##### observeCart() ```ts theme={null} observeCart(cartStore): () => void; ``` Report a second cart's `add_to_cart` / `remove_from_cart` through this hub, without making it THE cart: the currency and store id are still learned from the one `attachCart` was given, and attaching does not replace it. For a nested shop (a campaign storefront inside the site's provider) that shares the outer hub rather than loading the pixels twice. Returns the detach function. ###### Parameters | Parameter | Type | | - | - | | `cartStore` | [`CartStore`](/kit/api/react#cartstore) | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` ##### removeDestination() ```ts theme={null} removeDestination(destination): void; ``` Stop delivering to a destination. Its script, if it loaded one, stays on the page (nothing can unload it); it simply receives nothing more. Adding the same object back resumes it without a replay. ###### Parameters | Parameter | Type | | - | - | | `destination` | [`AnalyticsDestination`](#analyticsdestination) | ###### Returns `void` ##### start() ```ts theme={null} start(): void; ``` Begin delivering: load what consent allows, subscribe to changes. Idempotent, and `stop()` undoes it, so a React effect can call the pair on every mount/unmount. ###### Returns `void` ##### stop() ```ts theme={null} stop(): void; ``` ###### Returns `void` ##### track() ```ts theme={null} track(event): void; ``` Record an event and deliver it wherever consent allows. ###### Parameters | Parameter | Type | | - | - | | `event` | [`CommerceEvent`](#commerceevent) | ###### Returns `void` ##### trackPageView() ```ts theme={null} trackPageView(params?): void; ``` ###### Parameters | Parameter | Type | | - | - | | `params?` | [`CommerceEventParams`](#commerceeventparams-1) | ###### Returns `void` ##### trackPurchase() ```ts theme={null} trackPurchase(purchase, key): boolean; ``` Report an order once. Returns false when this browser already reported it (a reloaded thank-you page) — the event is then not sent again. `storeId` falls back to the hub's (its option, else the attached cart's); without any the key is still unique per order, just not shared with the platform's own surfaces. ###### Parameters | Parameter | Type | | - | - | | `purchase` | [`PurchaseEvent`](#purchaseevent) | | `key` | \{ `orderNumber?`: `string` \| `number`; `storeId?`: `string` \| `number` \| `null`; } | | `key.orderNumber?` | `string` \| `number` | | `key.storeId?` | `string` \| `number` \| `null` | ###### Returns `boolean` *** ### AsyncResource One in-flight fetch and its result, observable, with no framework attached. The non-React twin of `react/use-async.ts`, and the same non-promise: this is NOT a cache. shopkit ships no data-layer opinion — it exists so the elements layer can load a product list without the package growing a query library. A superseded run is aborted and its late response discarded, which is what a search-as-you-type box needs: `run()` called five times must land the fifth answer, not whichever server replied last. #### Type Parameters | Type Parameter | | - | | `T` | #### Constructors ##### Constructor ```ts theme={null} new AsyncResource(initialData?): AsyncResource; ``` ###### Parameters | Parameter | Type | | - | - | | `initialData?` | `T` \| `null` | ###### Returns [`AsyncResource`](#asyncresource)\<`T`> #### Properties ##### getSnapshot() ```ts theme={null} getSnapshot: () => AsyncSnapshot; ``` ###### Returns [`AsyncSnapshot`](#asyncsnapshot)\<`T`> ##### subscribe() ```ts theme={null} subscribe: (listener) => () => void; ``` ###### Parameters | Parameter | Type | | - | - | | `listener` | () => `void` | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` #### Methods ##### abort() ```ts theme={null} abort(): void; ``` Cancel the in-flight run, if any, without changing the last result. ###### Returns `void` ##### hydrate() ```ts theme={null} hydrate(data): void; ``` Adopt a result fetched elsewhere — a server render passing its data in. ###### Parameters | Parameter | Type | | - | - | | `data` | `T` \| `null` | ###### Returns `void` ##### run() ```ts theme={null} run(operation): Promise; ``` Start (or restart) the operation, cancelling whatever was in flight. Resolves to the result, or to null when the run failed or was superseded — errors are captured on the snapshot rather than thrown, so a caller in an event handler cannot produce an unhandled rejection. ###### Parameters | Parameter | Type | | - | - | | `operation` | (`signal`) => `Promise`\<`T`> | ###### Returns `Promise`\<`T` | `null`> *** ### CartResource The shopper's cart. Two layers live here. The plain methods (`create`, `get`, `addItem`, …) are a thin, stateless mapping of the Cart API. The `current`/`ensure` pair adds the one piece of state a storefront always ends up writing itself: remembering WHICH cart this visitor has, in a way that works the same in the browser, in a server component and in a server action. #### Constructors ##### Constructor ```ts theme={null} new CartResource( transport, scopes, store, storefront?, currency?): CartResource; ``` ###### Parameters | Parameter | Type | | - | - | | `transport` | [`Transport`](#transport) | | `scopes` | [`ScopeGuard`](#scopeguard) | | `store` | [`SessionStore`](#sessionstore) | | `storefront?` | [`StorefrontBinding`](#storefrontbinding) \| `null` | | `currency?` | `CurrencyPreference` \| `null` | ###### Returns [`CartResource`](#cartresource) #### Methods ##### add() ```ts theme={null} add(item, options?): Promise; ``` Add to the remembered cart, creating it on first use. Recovers once from a cart the server has since dropped: a stale id in a month-old cookie would otherwise 404 the very first "add to cart" click of a returning visitor. ###### Parameters | Parameter | Type | | - | - | | `item` | [`AddCartItemInput`](#addcartiteminput) | | `options?` | [`CartCreateOptions`](#cartcreateoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1)> ##### addItem() ```ts theme={null} addItem( cartId, item, options?): Promise; ``` Add a product. Adding the same product+variant again increments the existing line rather than creating a second one, so callers do not have to look first. ###### Parameters | Parameter | Type | | - | - | | `cartId` | `string` | | `item` | [`AddCartItemInput`](#addcartiteminput) | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1)> ##### clear() ```ts theme={null} clear(options?): Promise; ``` Empty the basket: delete the REMEMBERED cart server-side and forget it locally, so the next `add()` starts a fresh one. ```ts theme={null} await shopkit.cart.clear() ``` The call a "Töm varukorgen" button wants, without the id bookkeeping [delete](#delete) needs. Three cases, none of them an error: * **No remembered cart** — nothing to clear, so no request is made. A visitor who never added anything, or a second click, causes no write. * **The cart is already gone** (404/410 from the delete — expired, or bought in another tab) — the goal was an empty basket and the shopper has one, so the stale id is forgotten all the same. Surfacing that as an error would leave a button that can never succeed, because the id it keeps retrying is the one that no longer resolves. * **Any other failure** (a network error, a 5xx) throws, and the id is KEPT: the cart may well still exist server-side, and forgetting it would strand those items in a cart this visitor can no longer reach. The checkout session id, if one is remembered, is left alone — a thank-you page still needs it to confirm an order already paid for. `fallbackCartId` is the cart to delete when NONE is remembered — a cart rendered from a server read that this browser's storage does not hold. A remembered id always wins over it. ###### Parameters | Parameter | Type | | - | - | | `options?` | [`RequestOptions`](#requestoptions) & `object` | ###### Returns `Promise`\<`void`> ##### create() ```ts theme={null} create(options?): Promise; ``` Create a new empty cart. Does not remember it — see [ensure](#ensure). On a client bound to a campaign storefront (or when `storefrontId` is passed here) the cart is created BOUND to that campaign: the platform prices it with the campaign's overrides on every read, and a checkout session created from it inherits the binding. Otherwise the request carries no body, as it always has. This is the stateless call, so any campaign may be named — pass the returned `cart.id` as `cartId` to `checkout.start()` to check it out. ###### Parameters | Parameter | Type | | - | - | | `options?` | [`CartCreateOptions`](#cartcreateoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1)> ##### current() ```ts theme={null} current(options?): Promise; ``` The remembered cart, WITHOUT creating one. Use this wherever a missing cart is a legitimate answer — a header badge, a server-rendered cart page — so a crawler or a first-time visitor does not cause a write. A remembered id that no longer resolves is forgotten and reported as null. ###### Parameters | Parameter | Type | | - | - | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1) | `null`> ##### currentId() ```ts theme={null} currentId(): Promise; ``` The remembered cart id, or null when this visitor has none yet. ###### Returns `Promise`\<`string` | `null`> ##### delete() ```ts theme={null} delete(cartId, options?): Promise; ``` Delete the cart server-side. Also forgets it locally. ###### Parameters | Parameter | Type | | - | - | | `cartId` | `string` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<`void`> ##### ensure() ```ts theme={null} ensure(options?): Promise; ``` The remembered cart, creating and remembering one if needed. This is the call that needs writable storage. In a read-only context (an RSC, which cannot set cookies) the cart is still created server-side and returned — it just is not remembered, so prefer calling it from a place that CAN write (a server action, a route handler, the browser). A cart it has to create is bound to the client's campaign storefront — see [create](#create). A cart it merely finds is returned as it is, which on a bound client is a cart this same client created, because a bound client remembers its cart under its own storage prefix. A per-call `storefrontId` may only restate the client's binding: this call reuses the remembered cart, and a different campaign could neither apply to it nor be remembered safely (see `StorefrontAttribution`). ###### Parameters | Parameter | Type | | - | - | | `options?` | [`CartCreateOptions`](#cartcreateoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1)> ##### get() ```ts theme={null} get(cartId, options?): Promise; ``` Fetch a cart by id, or null when it no longer exists. ###### Parameters | Parameter | Type | | - | - | | `cartId` | `string` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1) | `null`> ##### removeItem() ```ts theme={null} removeItem( cartId, itemId, options?): Promise; ``` ###### Parameters | Parameter | Type | | - | - | | `cartId` | `string` | | `itemId` | `string` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1)> ##### updateItem() ```ts theme={null} updateItem( cartId, itemId, quantity, options?): Promise; ``` Set an absolute quantity on a cart LINE (`item.id`, not the product id). ###### Parameters | Parameter | Type | | - | - | | `cartId` | `string` | | `itemId` | `string` | | `quantity` | `number` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Cart`](#cart-1)> *** ### CategoriesResource The shop's category tree. Read-only for a storefront credential. #### Constructors ##### Constructor ```ts theme={null} new CategoriesResource(transport, scopes): CategoriesResource; ``` ###### Parameters | Parameter | Type | | - | - | | `transport` | [`Transport`](#transport) | | `scopes` | [`ScopeGuard`](#scopeguard) | ###### Returns [`CategoriesResource`](#categoriesresource) #### Methods ##### get() ```ts theme={null} get(categoryId, options?): Promise; ``` A single category by prefixed (`cat_12`) or numeric id, or null. A bare number is prefixed on the way out — the gateway validates the path param against `^cat_\d+$` and 400s a plain `12`, the same trap `products.search({ categoryId })` already normalises away. ###### Parameters | Parameter | Type | | - | - | | `categoryId` | `string` \| `number` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Category`](#category) | `null`> ##### list() ```ts theme={null} list(params?): Promise>; ``` One page of categories. Pass `root: true` for the top level, or a `parentId` (prefixed `cat_…`) to walk one level down. ###### Parameters | Parameter | Type | | - | - | | `params?` | [`CategoryListParams`](#categorylistparams) & [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Page`](#page)\<[`Category`](#category)>> *** ### CheckoutResource Checkout, as a headless storefront uses it: build a session from a cart, hand the shopper to the hosted Quickbutik checkout, then confirm the order when they come back. Payment itself is deliberately NOT part of this surface. The hosted checkout owns the PSP integration, PCI scope, 3-D Secure, wallets and the payment retry logic — the storefront owns the catalog, the cart and the thank-you page. #### Constructors ##### Constructor ```ts theme={null} new CheckoutResource( transport, scopes, store, config, cart, currency?, consent?): CheckoutResource; ``` ###### Parameters | Parameter | Type | | - | - | | `transport` | [`Transport`](#transport) | | `scopes` | [`ScopeGuard`](#scopeguard) | | `store` | [`SessionStore`](#sessionstore) | | `config` | [`ResolvedShopkitConfig`](#resolvedshopkitconfig) | | `cart` | [`CartResource`](#cartresource) | | `currency?` | `CurrencyPreference` \| `null` | | `consent?` | [`ConsentResource`](#consentresource) | ###### Returns [`CheckoutResource`](#checkoutresource) #### Methods ##### buyNow() ```ts theme={null} buyNow( item, input, options?): Promise; ``` Add a product and hand off immediately — the "Buy now" button. Uses the remembered cart, so an existing basket is carried along rather than replaced. Returns the URL rather than navigating, exactly as [start](#start-2) does; `useCheckout().buyNow` and `` are the navigating wrappers. The result also carries `cart` — the cart as the add left it — so a caller that keeps its own cart state (the shared `CartStore` does) can fold it in without a second read: a page that stays put (`no-redirect`, a new tab) or is restored from the back/forward cache must not show a badge that missed the item it just added. ###### Parameters | Parameter | Type | | - | - | | `item` | [`AddCartItemInput`](#addcartiteminput) | | `input` | [`StartCheckoutInput`](#startcheckoutinput) | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`BuyNowResult`](#buynowresult)> ##### confirmation() ```ts theme={null} confirmation(sessionId, options?): Promise; ``` One snapshot of the order-creation status for a handoff. Order creation is asynchronous: the PSP authorizes, then the platform builds the order. Between those two moments the status is `processing_payment` and there is no order number yet. Takes either handle — a checkout-v2 session id or a legacy order uuid (both arrive as `StartCheckoutResult.handoffId`); the platform resolves which it is. Read the statuses with care on a legacy handoff: that checkout leaves a failed payment looking untouched, so `no_attempt` means "not paid yet", NOT "the shopper never tried". See `LegacyHandoff`. ###### Parameters | Parameter | Type | | - | - | | `sessionId` | `string` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`SessionConfirmation`](#sessionconfirmation)> ##### createSession() ```ts theme={null} createSession(input, options?): Promise; ``` Create a checkout session for a cart and remember it. `successUrl` may be any `https` URL — `http` only for `localhost`/loopback — see [CreateSessionInput.successUrl](#successurl-2). The same rule applies to `cancelUrl` and `backUrl` (where the checkout's "continue shopping" links point). Only the ORIGIN of `successUrl` is used for the return redirect. A campaign storefront (`storefrontId` on the input, else the client's `storefront`) is sent along with its `surface`; the platform then prices the session with the campaign, refuses with a typed error when the campaign is not live, a quantity limit is exceeded or the cart belongs to another campaign (see `storefrontRefusal()`), and puts the campaign on the order. With neither set, nothing is sent and a cart that was created bound to a campaign passes its own binding on server-side. Because the caller names the cart here, any campaign may be named. ###### Parameters | Parameter | Type | | - | - | | `input` | [`CreateSessionInput`](#createsessioninput) | | `options?` | [`RequestOptions`](#requestoptions) & `object` | ###### Returns `Promise`\<[`CheckoutSession`](#checkoutsession)> ##### currentSessionId() ```ts theme={null} currentSessionId(): Promise; ``` The remembered checkout session id, or null. ###### Returns `Promise`\<`string` | `null`> ##### embedUrl() ```ts theme={null} embedUrl(input): string; ``` The URL of the checkout document to FRAME for a session — `/embed/{storeId}/{sessionId}`. The sibling of [hostedUrl](#hostedurl), and everything that doc says about `storeId` applies here verbatim: it is the shop's NUMERIC id (`Cart.storeId`), not the prefix in the publishable key, and both ids ride the path because storage is partitioned — or absent — inside a third-party frame, so the URL has to carry everything needed to rehydrate. A distinct top-level `/embed/` prefix rather than a path under `/checkout/`: the two documents are not interchangeable. The embed one is chrome-less, never navigates itself, and is served with a `frame-ancestors` header naming the session's recorded embed origin — so a session created WITHOUT an `embed` block renders a refusal here, whatever URL you build. [mount](#mount) is the supported way to reach this; build it by hand only when you are framing the checkout yourself. ###### Parameters | Parameter | Type | | - | - | | `input` | `string` \| [`HostedCheckoutUrlInput`](#hostedcheckouturlinput) | ###### Returns `string` ##### finalize() ```ts theme={null} finalize(): Promise; ``` Forget the cart and session ids. Called automatically once a confirmation comes back `completed`, so the next visit starts a clean basket instead of resurrecting a cart that has already been bought. The shop's numeric store id remembered off the cart is kept, here as everywhere a cart is forgotten (a header badge finding the cart gone, `cart.clear()`): it is a constant of the shop, not of the order, and it is what a thank-you page keys the `purchase` event on (`rememberedStoreId()`). A reload of that page — with the session id on its URL — has to build the same key as the first visit, or the order is counted twice. The copy kept next to the checkout session goes with the session, as documented on `SessionStore`. ###### Returns `Promise`\<`void`> ##### getSession() ```ts theme={null} getSession(sessionId, options?): Promise; ``` Read a session. Useful on the thank-you page to show what was bought (`data.cart_products`, `data.order_total`) without a second cart lookup. Null when the session is unknown or has been cleaned up. ###### Parameters | Parameter | Type | | - | - | | `sessionId` | `string` | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`CheckoutSessionSnapshot`](#checkoutsessionsnapshot) | `null`> ##### hostedUrl() ```ts theme={null} hostedUrl(input): string; ``` The URL of the checkout-v2 hosted checkout for a session. `/checkout/{storeId}/{sessionId}` — the canonical, shareable, resumable form. Both ids are in the path because the checkout must be able to bootstrap itself from the URL alone (a link opened on another device has no storage to fall back on). **checkout-v2 only, and it asks the platform nothing.** A shop on the legacy checkout needs a URL naming an order the platform has to create first, which no synchronous local builder can produce — so for such a shop this returns a link that cannot be opened. Prefer [start](#start-2), which asks which checkout the shop runs and returns the right URL either way; reach for this only when you hold a checkout-v2 session id and want the URL without a round trip. `storeId` is the shop's NUMERIC id, `Cart.storeId`. It is not the prefix in the publishable key (`shopkit.shopPrefix`, `101928Y`), which the checkout answers with "We couldn't find 101928Y". The id is taken from the input when given, else from the one remembered off the last cart this client received; when neither exists this throws rather than guess — pass `storeId: cart.storeId`, or use [start](#start-2), which has the cart in hand. ###### Parameters | Parameter | Type | | - | - | | `input` | `string` \| [`HostedCheckoutUrlInput`](#hostedcheckouturlinput) | ###### Returns `string` ##### mount() ```ts theme={null} mount( container, input, options?): Promise; ``` Render the checkout INSIDE this page, in an iframe served from the checkout's own origin. ```ts theme={null} const checkout = await shopkit.checkout.mount("#checkout", { successUrl: "/thanks", backUrl: "/cart", }) checkout.on("complete", ({ orderNumber }) => track(orderNumber)) ``` One request, not two: this is [start](#start-2)'s call to `/checkout/handoff` with an `embed` block added, so a mounted checkout costs a storefront exactly what a redirected one does. **It always resolves.** When there is nothing to frame — the shop runs the legacy checkout, the platform returned no embed URL, or this page cannot navigate its own top window — the handle comes back in its `fallback` state, emits `fallback`, and (unless `fallbackRedirect: false`) sends the shopper to the hosted checkout instead. None of those is a bug in the calling page and none of them is retryable, so none of them throws. A genuine failure — no cart, a rejected key, a 500 — still rejects, exactly as `start()` would. The same hosted URL is kept for one more case, decided later: a frame that is built but never answers (this page is not the origin the session was created for, typically). Fifteen seconds in, the handle takes the frame down, moves to `fallback` with reason `handshake-timeout`, and sends the shopper the same way — so a misconfigured `embedOrigin` costs a redirect, not a sale. **One checkout per container.** Mounting into an element that already shows one destroys the earlier handle — its frame, its listeners, its handshake timer — before the new frame goes in, so a page that calls `mount()` again from a re-render or a "try again" button ends up with one checkout, not two stacked. Last mount wins. The platform hands the same cart the same session back, so the new frame shows the same checkout at the same step; nothing is charged twice. `` lives by the same rule when it is detached and put back. Keep the handle if you want to `destroy()` it yourself; you do not have to for a second `mount()`. Browser only: it builds a DOM node and listens for `message`. ###### Parameters | Parameter | Type | | - | - | | `container` | `string` \| `Element` | | `input` | [`MountCheckoutInput`](#mountcheckoutinput) | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`EmbeddedCheckout`](#embeddedcheckout)> ##### parseReturnUrl() ```ts theme={null} parseReturnUrl(url): HostedCheckoutReturn | null; ``` Parse the hosted checkout's post-payment redirect. The shopper is sent to `/success/?hash=…&t=…` — note that only the ORIGIN of `successUrl` is used, so this path is where a headless storefront must mount its thank-you route. Both checkouts return this way, the legacy one included (see `LegacyHandoff`); the handle to confirm the order by is the one `start()` remembered either way. `hash` is a legacy integrity token and is returned for completeness only; treat the order as real once [confirmation](#confirmation) says `completed`. ###### Parameters | Parameter | Type | | - | - | | `url` | `string` \| `URL` | ###### Returns [`HostedCheckoutReturn`](#hostedcheckoutreturn) | `null` ##### pollConfirmation() ```ts theme={null} pollConfirmation(sessionId, options?): Promise; ``` Poll until the order exists, the payment terminally fails, or the caps are reached. This is what a thank-you page should call. A `timeout` outcome is NOT a failure — the order may still land. Show "we are still processing your order" and let the customer refresh. On a legacy handoff `timeout` is the NORMAL outcome for a shopper who has not paid yet, because that checkout never reports `failed`; do not present it as an error there. ###### Parameters | Parameter | Type | | - | - | | `sessionId` | `string` | | `options?` | [`PollConfirmationOptions`](#pollconfirmationoptions) | ###### Returns `Promise`\<[`ConfirmationOutcome`](#confirmationoutcome)> ##### rememberedStoreId() ```ts theme={null} rememberedStoreId(): string | null; ``` The shop's numeric store id as remembered from the last checkout session or cart this client saw, or null when nothing is known yet — the value the return leg needs after the cart is gone (a purchase event's dedup key, `hostedUrl()` without a cart). Synchronous and request-free, like `hostedUrl()`; see `SessionStore.peekStoreId` for what "remembered" covers. The session's copy is consulted first because that is the one still alive on a thank-you page. ###### Returns `string` | `null` ##### resume() ```ts theme={null} resume( container, sessionId, input?): Promise; ``` Frame an EXISTING session — the redirect break-out's landing. A redirect payment method (Klarna, Swish, iDEAL, a full-page 3-D Secure) takes the whole window to the PSP and comes back to the checkout's own origin, which bounces to the page that created the session with `?qb_checkout_session=` on it. This is what that page calls with the id: no handoff, no new session, straight back into the frame the shopper was already in, which resumes at its confirmation step. `` and `` do this for you. Reach for it directly only when you route that parameter yourself. The URL is built locally, because there is no handoff call to ask. Pass `storeId` — the return URL carries it as `qb_checkout_shop`, next to the session id (`readReturnedCheckout()` reads both) — and no storage is involved at all. Without it the id remembered with the session, then the one off the last cart, is used; only when none of the three exists does this reject. Degrades the way [mount](#mount) does when the frame never answers: the hosted checkout URL for the same session is built from the same inputs, and a `handshake-timeout` sends the shopper there (unless `fallbackRedirect: false`). A return leg that lands on the wrong origin — a `www` redirect between leaving and coming back — thus still reaches the confirmation, on the hosted checkout, instead of an empty box. ###### Parameters | Parameter | Type | | - | - | | `container` | `string` \| `Element` | | `sessionId` | `string` | | `input?` | [`ResumeCheckoutInput`](#resumecheckoutinput) | ###### Returns `Promise`\<[`EmbeddedCheckout`](#embeddedcheckout)> ##### start() ```ts theme={null} start(input, options?): Promise; ``` Cart → session → handoff URL, in one call. The 90%-case entry point for a "Checkout" button. Returns the URL rather than navigating, so it works unchanged in a server action (`redirect(url)`), a route handler (302) and the browser (`location.assign`). The URL's store id comes from the cart itself — the only place the storefront API states the shop's numeric id. On a server client (one built with a `cookies` accessor) the shopper's consent decision is forwarded on the URL too, read from the request's `qb_consent` cookie: `consentCategories`, and the GA client and session ids when analytics is granted and the accessor has `getAll()`. That is what lets the hosted checkout set Consent Mode before its own tags load. `consent: false` in the config turns it off. In a browser the React hooks and the elements decorate the URL from the live consent store instead. ###### Parameters | Parameter | Type | | - | - | | `input` | [`StartCheckoutInput`](#startcheckoutinput) | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`StartCheckoutResult`](#startcheckoutresult)> ##### syncCart() ```ts theme={null} syncCart(sessionId, options?): Promise; ``` Re-read the cart into a session whose snapshot has gone stale. Session creation is **idempotent on `cartId`** server-side: a second `POST /checkout/sessions` for the same cart returns the FIRST session, complete with the cart as it looked back then. That is right for a retry and wrong for a shopper who went to checkout, came back, added something, and set off again — their new lines would never reach the checkout, with no error anywhere to say so. Patching `cart: {}` is the platform's own "rehydrate from the Cart API" instruction, and is what the hosted checkout does when the shopper edits quantities inside it. Only patches when the snapshot actually differs, so a session the shopper is midway through is not needlessly disturbed. Pass `cart` when you already have it (`start()` does) and the check costs no request at all. ###### Parameters | Parameter | Type | | - | - | | `sessionId` | `string` | | `options?` | [`RequestOptions`](#requestoptions) & `object` | ###### Returns `Promise`\<[`CheckoutSessionSnapshot`](#checkoutsessionsnapshot) | `null`> *** ### ConsentResource The shopper's consent decision as this client sees it, and the settings every part of the kit has to agree on to read it. Not a request to the platform: the decision lives in the `qb_consent` cookie on the storefront's own origin, so on a server it is read through the same `cookies` accessor the cart id is, and in a browser from `document.cookie`. ```ts theme={null} // A Next.js layout: no banner flash for a shopper who already decided. const shopkit = await readOnlyShopkit() const consent = await shopkit.consent.read() ``` #### Constructors ##### Constructor ```ts theme={null} new ConsentResource(config): ConsentResource; ``` ###### Parameters | Parameter | Type | | - | - | | `config` | [`ResolvedShopkitConfig`](#resolvedshopkitconfig) | ###### Returns [`ConsentResource`](#consentresource) #### Accessors ##### cookieName ###### Get Signature ```ts theme={null} get cookieName(): string; ``` The cookie the decision is stored in. ###### Returns `string` ##### enabled ###### Get Signature ```ts theme={null} get enabled(): boolean; ``` False when the config says `consent: false`. ###### Returns `boolean` ##### revision ###### Get Signature ```ts theme={null} get revision(): number; ``` The cookie-policy revision a stored decision must match. ###### Returns `number` #### Methods ##### decorateHandoff() ```ts theme={null} decorateHandoff(url): Promise; ``` A hosted checkout URL with the decision from this client's cookie accessor on it (`consentCategories`, plus `gaClientId` / `gaSessionId` when analytics is granted and the accessor has `getAll()`). What `checkout.start()` applies on a server client. The URL comes back untouched when consent is off or the client has no cookie accessor: a browser client's handoff is decorated by the React hooks and the elements instead, from the live consent store. ###### Parameters | Parameter | Type | | - | - | | `url` | `string` | ###### Returns `Promise`\<`string`> ##### read() ```ts theme={null} read(): Promise; ``` The decision, from this client's cookies: the `cookies` accessor when one was configured, else `document.cookie`, else undecided. A decision made under another revision, or a cookie that is not one, reads as undecided. ###### Returns `Promise`\<[`ConsentState`](#consentstate-1)> *** ### ConsentStore The shopper's consent decision, observable. One per page, shared by the banner, the "Cookie settings" link in the footer, every `` and the analytics hub — the same shape as `CartStore` (`subscribe` / `getSnapshot`, an immutable snapshot replaced on every change) so `useSyncExternalStore` and the elements' bindings can read it the same way they read the cart. The decision is the cookie's; this object is a view over it that can also write. Reading happens once, at construction (or never, with `initialState`), and every write goes through `save()` — there is no second source of truth to drift from. #### Constructors ##### Constructor ```ts theme={null} new ConsentStore(options?): ConsentStore; ``` ###### Parameters | Parameter | Type | | - | - | | `options?` | [`ConsentStoreOptions`](#consentstoreoptions) | ###### Returns [`ConsentStore`](#consentstore) #### Properties ##### getSnapshot() ```ts theme={null} getSnapshot: () => ConsentSnapshot; ``` ###### Returns [`ConsentSnapshot`](#consentsnapshot) ##### revision ```ts theme={null} readonly revision: number; ``` ##### subscribe() ```ts theme={null} subscribe: (listener) => () => void; ``` ###### Parameters | Parameter | Type | | - | - | | `listener` | () => `void` | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` #### Accessors ##### pristine ###### Get Signature ```ts theme={null} get pristine(): boolean; ``` True while the store still holds the state it started from: no decision saved, reset or adopted since. A provider uses it to tell "nothing known yet" from "the shopper (or something) has spoken" before applying a state of its own. ###### Returns `boolean` #### Methods ##### acceptAll() ```ts theme={null} acceptAll(): void; ``` ###### Returns `void` ##### allows() ```ts theme={null} allows(category): boolean; ``` Whether a category may be used right now. `necessary` always may; the others only after an explicit yes — undecided is a no. ###### Parameters | Parameter | Type | | - | - | | `category` | [`ConsentCategory`](#consentcategory) | ###### Returns `boolean` ##### closeSettings() ```ts theme={null} closeSettings(): void; ``` ###### Returns `void` ##### getState() ```ts theme={null} getState(): ConsentState; ``` The decision alone, without the UI flag — what gets persisted and forwarded. ###### Returns [`ConsentState`](#consentstate-1) ##### hydrate() ```ts theme={null} hydrate(state): void; ``` Adopt a state read elsewhere — the server's, or one re-read from a raw cookie value. Does not persist and does not announce: this is catching up with a decision, not making one. ###### Parameters | Parameter | Type | | - | - | | `state` | [`ConsentState`](#consentstate-1) \| `null` | ###### Returns `void` ##### openSettings() ```ts theme={null} openSettings(): void; ``` ###### Returns `void` ##### rejectAll() ```ts theme={null} rejectAll(): void; ``` Necessary only. As prominent a choice as "accept all", by law. ###### Returns `void` ##### reload() ```ts theme={null} reload(): void; ``` Re-read `document.cookie`, for a page that knows another tab decided. ###### Returns `void` ##### reset() ```ts theme={null} reset(): void; ``` Withdraw consent: forget the decision and ask again. Withdrawal must be as easy as consent, so this is one call — the banner reappears, Consent Mode is updated to denied, and nothing optional fires until the next decision. Scripts already on the page are not unloaded (nothing can unload them); they simply receive nothing more. ###### Returns `void` ##### save() ```ts theme={null} save(choice): void; ``` Record a decision. Persists it (unless `persist: false`), closes the preferences panel and announces it on `document` as `qb:consent`, so a page's own scripts can react the way the hosted storefront's do. ###### Parameters | Parameter | Type | | - | - | | `choice` | [`ConsentChoice`](#consentchoice) | ###### Returns `void` *** ### EmbeddedCheckout A checkout rendered inside the merchant's own page, and the conversation with it. The iframe document is always served from the checkout's own origin, so the PSP integration, the same-origin API proxy and the wallet domain registrations keep working exactly as they do on the redirect path. What changes is who owns the window: the frame may not navigate anything, so every exit — the back link, a PSP redirect, the completed order — arrives here as a message and is performed by this host. A handle is also returned when there is nothing to embed (see [EmbeddedCheckoutFallbackReason](#embeddedcheckoutfallbackreason)). That is not an error and does not throw: it is an expected shop configuration, reported as a `fallback` event on a handle whose `state` is `"fallback"`. An embed handle whose frame never answers ends up in the same place: the frame is removed, `state` flips to `"fallback"`, and the same event carries the hosted checkout URL — so one listener covers every way the shopper can end up on the hosted checkout. #### Constructors ##### Constructor ```ts theme={null} new EmbeddedCheckout(init): EmbeddedCheckout; ``` ###### Parameters | Parameter | Type | | - | - | | `init` | [`EmbeddedCheckoutInit`](#embeddedcheckoutinit) | ###### Returns [`EmbeddedCheckout`](#embeddedcheckout) #### Properties ##### sessionId ```ts theme={null} readonly sessionId: string | null; ``` The session being checked out, when one is known. #### Accessors ##### iframe ###### Get Signature ```ts theme={null} get iframe(): HTMLIFrameElement | null; ``` The frame, or null in a fallback handle. ###### Returns `HTMLIFrameElement` | `null` ##### state ###### Get Signature ```ts theme={null} get state(): "fallback" | "embed"; ``` `"embed"` while framed, `"fallback"` when there was nothing to frame — or when the frame there was never answered and has been taken down. ###### Returns `"fallback"` | `"embed"` #### Methods ##### cartUpdated() ```ts theme={null} cartUpdated(): void; ``` Tell the frame that the cart it is checking out has changed here. The session's cart is a snapshot taken when the session was created, so a page that lets the shopper edit the cart while the checkout is on screen — its own quantity steppers, an "add a gift box" button, a cross-sell strip — has to say so, or the frame goes on showing (and charging for) the cart as it stood a moment ago. The frame re-reads the cart from the platform and re-prices everything that hangs off it; nothing about the new cart travels in this message. `` and React's `` call this for you, off the kit's own cart store. Call it yourself only when you drove `mount()` by hand, or when you change the cart through something other than `Quickbutik.cart` — and then only after the change has actually been saved, because the frame reads the server's cart, not yours. Held — not dropped — before the frame has said `ready`, and ignored by a fallback handle: there is no frame to tell, and there never will be. It is cheap and safe to over-call — the frame coalesces a burst into at most one extra read. Holding it is the whole point. The frame does NOT re-read the cart as it boots: the session's cart is a snapshot taken when the session was created, and this message is the only thing that refreshes it (see `use-cart-rehydrate.ts` in checkout-frontend, and EMBED\_CONTRACT §3). The window between the frame being built and its first `ready` is the iframe load plus the frame's own session fetch — seconds on mobile — and a mutation dropped in it would be a shopper charged for the cart as it stood before they changed it. One flag, not a queue: the message carries nothing, so two of them say exactly what one says. ###### Returns `void` ##### destroy() ```ts theme={null} destroy(): void; ``` Remove the frame and every listener. Idempotent, and safe to call before the handshake completes — which is what React's StrictMode double-mount does on every development render. ###### Returns `void` ##### focus() ```ts theme={null} focus(): void; ``` Ask the frame to focus its first control. ###### Returns `void` ##### off() ```ts theme={null} off(type, handler): void; ``` ###### Type Parameters | Type Parameter | | - | | `T` *extends* keyof [`EmbeddedCheckoutEventMap`](#embeddedcheckouteventmap) | ###### Parameters | Parameter | Type | | - | - | | `type` | `T` | | `handler` | [`EmbeddedCheckoutHandler`](#embeddedcheckouthandler)\<`T`> | ###### Returns `void` ##### on() ```ts theme={null} on(type, handler): () => void; ``` Subscribe. Returns an unsubscribe, so a one-liner needs no `off`. ###### Type Parameters | Type Parameter | | - | | `T` *extends* keyof [`EmbeddedCheckoutEventMap`](#embeddedcheckouteventmap) | ###### Parameters | Parameter | Type | | - | - | | `type` | `T` | | `handler` | [`EmbeddedCheckoutHandler`](#embeddedcheckouthandler)\<`T`> | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` *** ### ProductController The variant-selection state machine for one product, with no framework attached. It owns nothing but a `VariantSelection` — every field on the snapshot is derived from `(product, selection)` by the pure functions in `variant-matrix.ts`. That is deliberate: the matrix is the only place variant logic lives, and both bindings over it (React's `useProductState`, the `` element) are glue. Built for `useSyncExternalStore`, hence the cached snapshot: that hook compares snapshots by identity and would loop forever on a freshly-allocated object. The same caching is what lets the elements layer skip re-binding the DOM when nothing changed. #### Constructors ##### Constructor ```ts theme={null} new ProductController(product, options?): ProductController; ``` ###### Parameters | Parameter | Type | | - | - | | `product` | [`Product`](#product-1) | | `options?` | [`ProductControllerOptions`](#productcontrolleroptions) | ###### Returns [`ProductController`](#productcontroller) #### Properties ##### getSnapshot() ```ts theme={null} getSnapshot: () => ProductSnapshot; ``` ###### Returns [`ProductSnapshot`](#productsnapshot) ##### subscribe() ```ts theme={null} subscribe: (listener) => () => void; ``` ###### Parameters | Parameter | Type | | - | - | | `listener` | () => `void` | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` #### Accessors ##### product ###### Get Signature ```ts theme={null} get product(): Product; ``` ###### Returns [`Product`](#product-1) #### Methods ##### clear() ```ts theme={null} clear(optionId): void; ``` Unset one group's choice. ###### Parameters | Parameter | Type | | - | - | | `optionId` | `number` | ###### Returns `void` ##### reset() ```ts theme={null} reset(): void; ``` Unset every choice. ###### Returns `void` ##### select() ```ts theme={null} select(optionId, valueId): void; ``` Choose a value. Contradicting choices are cleared, not refused. ###### Parameters | Parameter | Type | | - | - | | `optionId` | `number` | | `valueId` | `number` | ###### Returns `void` ##### selectVariant() ```ts theme={null} selectVariant(variantId): void; ``` Jump straight to a variant, e.g. from a `?variant=` deep link. ###### Parameters | Parameter | Type | | - | - | | `variantId` | `number` | ###### Returns `void` ##### setProduct() ```ts theme={null} setProduct(product, options?): void; ``` Point the controller at a different product, resetting the selection. A quick-view that swaps items reuses one controller, and the previous product's option ids are meaningless against the new one — keeping them would resolve a variant that does not exist. Re-selecting the SAME product is a no-op, so a re-render that happens to pass an equal object does not throw away what the shopper picked. ###### Parameters | Parameter | Type | | - | - | | `product` | [`Product`](#product-1) | | `options?` | [`ProductControllerOptions`](#productcontrolleroptions) | ###### Returns `void` *** ### ProductsResource The shop's public catalog. Reads hit api-core's storefront controller, which serves only visible products and omits everything a shopper has no business seeing (cost prices, suppliers, internal notes). There is no write surface here on purpose: a publishable key cannot create or edit products. #### Constructors ##### Constructor ```ts theme={null} new ProductsResource( transport, scopes, storefront?, currency?): ProductsResource; ``` ###### Parameters | Parameter | Type | | - | - | | `transport` | [`Transport`](#transport) | | `scopes` | [`ScopeGuard`](#scopeguard) | | `storefront?` | [`StorefrontBinding`](#storefrontbinding) \| `null` | | `currency?` | `CurrencyPreference` \| `null` | ###### Returns [`ProductsResource`](#productsresource) #### Methods ##### get() ```ts theme={null} get(productId, options?): Promise; ``` A single product by its prefixed (`prod_123`) or numeric id. Returns null when it does not exist or is not visible. A bare number is prefixed on the way out — the gateway validates the path param against `^prod_\d+$` and 400s a plain `27`. See normalizePrefixedId. ###### Parameters | Parameter | Type | | - | - | | `productId` | `string` \| `number` | | `options?` | [`RequestOptions`](#requestoptions) & [`ProductReadOptions`](#productreadoptions) | ###### Returns `Promise`\<[`Product`](#product-1) | `null`> ##### getBySlug() ```ts theme={null} getBySlug(slug, params?): Promise; ``` Find a product by its URL slug. **This walks pages until it matches.** The storefront product list accepts only `limit`/`offset` — there is no `?slug=` filter to push the lookup server-side — so the cost grows with the catalog. That is fine for a small shop and for build-time generation, and wrong for a hot request path on a large one. Two ways to avoid it: * cache the result per slug (in Next.js, wrap the call in `cache()` and set a revalidate window), or * build a slug → id map once at deploy time from [listAll](#listall) and look the id up with [get](#get-4), which is a single request. Matching is case-insensitive and ignores surrounding slashes, so a slug taken straight from a route param works. Returns null when nothing matches. Every page it walks is priced for the same campaign — the client's, or `storefrontId` — so the product it returns carries that campaign's prices. ###### Parameters | Parameter | Type | | - | - | | `slug` | `string` | | `params?` | `object` & [`RequestOptions`](#requestoptions) & [`ProductReadOptions`](#productreadoptions) | ###### Returns `Promise`\<[`Product`](#product-1) | `null`> ##### list() ```ts theme={null} list(params?): Promise>; ``` One page of products, newest configured order first. ###### Parameters | Parameter | Type | | - | - | | `params?` | [`ProductListParams`](#productlistparams) | ###### Returns `Promise`\<[`Page`](#page)\<[`Product`](#product-1)>> ##### listAll() ```ts theme={null} listAll(params?): Promise; ``` Walk every page. Convenience for build-time generation (static params, sitemaps) — not something to call while rendering a request. ###### Parameters | Parameter | Type | | - | - | | `params?` | `object` & [`RequestOptions`](#requestoptions) & [`ProductReadOptions`](#productreadoptions) | ###### Returns `Promise`\<[`Product`](#product-1)\[]> ##### search() ```ts theme={null} search(params?): Promise>; ``` Filter, sort and page the catalog **server-side**. This is the method to reach for when building a real listing. `list()` offers nothing but `limit`/`cursor`, which forces a storefront to read the whole catalog and filter in its own process — fine for a handful of products, wrong the moment there are thousands. ```ts theme={null} const page = await shopkit.products.search({ search: "merino", sortBy: "price", sortOrder: "asc", minPrice: 20000, // minor units — 200,00 kr categoryId: "cat_12", limit: 24, }) page.data // Product[] page.next_cursor // feed back as `cursor` ``` Two things it deliberately does not do: * **No facet counts.** The gateway rebuilds every paginated response into `{ data, has_more, next_cursor }`, so an aggregate could not survive the trip even if the server sent one. Derive facet values from `categories.list()`, or keep your own index. * **No option-value filter.** Option values are per-product rows, so "Svart" is a different id on every product and a cross-catalog filter would have to match on an unindexed name column. Only visible products are ever returned, and — unlike `list()` — visibility is applied in the query rather than after paging, so pages come back full. ###### Parameters | Parameter | Type | | - | - | | `params?` | [`ProductSearchParams`](#productsearchparams) | ###### Returns `Promise`\<[`Page`](#page)\<[`Product`](#product-1)>> *** ### SessionStore What shopkit remembers between requests, and nothing else: the cart id, the checkout session id, and the numeric id of the shop — twice. Deliberately minimal: all of them are opaque server-side handles, so a leaked or stale value costs at most a fresh cart. No prices, no PII and no credential is ever persisted — that is what keeps a cookie-based store safe to use without consent banners in most jurisdictions (it is strictly necessary functionality) and what makes "just clear it" a valid recovery. The store id is the odd one out. shopkit never needs it to talk to the API (the publishable key already scopes every request to one shop), but it is the one value the hosted checkout URL is built from, and the API only ever states it on a cart. Remembering it off every cart that passes through is what lets `checkout.hostedUrl()` stay a synchronous, request-free call. It is kept twice because the two copies are written at different times and expire on different clocks. The copy next to the cart id is refreshed off every cart and expires with the cart's TTL; the copy next to the checkout session id is written on handoff and goes with the session (`clearCheckoutSessionId`), so the return leg of an embedded checkout can build `/embed/{storeId}/{sessionId}` from a value no cart read disturbs. Neither copy is removed when the cart is FORGOTTEN: the platform drops the cart the moment an order is created, which on a redirect payment (Klarna, Swish) is normally before the shopper is back on the page, and the thank-you page then keys its `purchase` event on the id (`checkout.rememberedStoreId()`). A reload of that page, after a header badge has found the cart gone and the completed confirmation has forgotten the session, must still find the same value or the order is counted twice. Only `clear()` forgets it. #### Constructors ##### Constructor ```ts theme={null} new SessionStore( storage, prefix, ttlSeconds): SessionStore; ``` ###### Parameters | Parameter | Type | | - | - | | `storage` | [`StorageAdapter`](#storageadapter) | | `prefix` | `string` | | `ttlSeconds` | `number` | ###### Returns [`SessionStore`](#sessionstore) #### Properties ##### storage ```ts theme={null} readonly storage: StorageAdapter; ``` #### Methods ##### clear() ```ts theme={null} clear(): Promise; ``` Forget everything: the cart, the session and both copies of the store id. ###### Returns `Promise`\<`void`> ##### clearCartId() ```ts theme={null} clearCartId(): Promise; ``` ###### Returns `Promise`\<`void`> ##### clearCheckoutSessionId() ```ts theme={null} clearCheckoutSessionId(): Promise; ``` Forget the checkout session, and the store id remembered with it. ###### Returns `Promise`\<`void`> ##### clearStoreId() ```ts theme={null} clearStoreId(): Promise; ``` Forget the cart's copy of the store id. The checkout's copy stays. Only `clear()` calls this: forgetting a cart keeps the id (see the class doc). ###### Returns `Promise`\<`void`> ##### getCartId() ```ts theme={null} getCartId(): Promise; ``` ###### Returns `Promise`\<`string` | `null`> ##### getCheckoutSessionId() ```ts theme={null} getCheckoutSessionId(): Promise; ``` ###### Returns `Promise`\<`string` | `null`> ##### getStoreId() ```ts theme={null} getStoreId(): Promise; ``` The remembered numeric shop id, or null. Also primes [peekStoreId](#peekstoreid). ###### Returns `Promise`\<`string` | `null`> ##### peekCheckoutStoreId() ```ts theme={null} peekCheckoutStoreId(): string | null; ``` The checkout session's store id without waiting on storage — the second fallback of `hostedUrl()` and `embedUrl()`, after the cart's copy. Same rules as [peekStoreId](#peekstoreid). ###### Returns `string` | `null` ##### peekStoreId() ```ts theme={null} peekStoreId(): string | null; ``` The remembered store id WITHOUT waiting on storage — what the synchronous `hostedUrl()` reads. Answers from memory first (every cart the client received set it), then from storage when the adapter answers synchronously — memory, `localStorage`, `document.cookie` and a request cookie jar all do, which is what carries the value across page loads and server requests. An adapter that only answers with a promise (Next's `cookies()`) cannot be consulted here; until a cart has been read in that request the answer is null and the caller has to be told the id explicitly. ###### Returns `string` | `null` ##### setCartId() ```ts theme={null} setCartId(cartId): Promise; ``` ###### Parameters | Parameter | Type | | - | - | | `cartId` | `string` | ###### Returns `Promise`\<`void`> ##### setCheckoutSessionId() ```ts theme={null} setCheckoutSessionId(sessionId, storeId?): Promise; ``` Checkout sessions are short-lived by nature (one purchase attempt), so they get a much shorter TTL than the cart — a day is generous for a shopper who wanders off mid-payment and comes back. The stored value is the HANDOFF handle, which is a checkout-v2 session id for a shop on the current checkout and a legacy order uuid for a shop on the old one (see `StartCheckoutResult.handoffId`). Both are v4 UUIDs and both are what `checkout.confirmation()` takes, so nothing downstream has to tell them apart — but do not assume a stored value addresses a session. `storeId` is the shop's numeric id the session's URLs are built from, remembered alongside for as long as the session is (see the class doc). Best-effort, like [setStoreId](#setstoreid): the session id is the value nothing else can recover, so that write is the one allowed to fail loudly. ###### Parameters | Parameter | Type | | - | - | | `sessionId` | `string` | | `storeId?` | `string` \| `number` \| `null` | ###### Returns `Promise`\<`void`> ##### setStoreId() ```ts theme={null} setStoreId(storeId): Promise; ``` Remember the shop's numeric id, noted off every cart. Written with the cart's TTL, and kept when the cart is forgotten (see the class doc). Best-effort on the storage side. This runs on every cart READ, and a cart page must not fail because its cookie jar is read-only (an RSC) or full. The in-memory copy is kept regardless, so `hostedUrl()` works for the rest of the request either way. Storage is only written when the value is new, so a server request that merely reads the cart does not emit a cookie. ###### Parameters | Parameter | Type | | - | - | | `storeId` | `string` \| `number` | ###### Returns `Promise`\<`void`> *** ### ShopkitApiError A non-2xx response from the Quickbutik API. #### Extends * [`ShopkitError`](#shopkiterror) #### Constructors ##### Constructor ```ts theme={null} new ShopkitApiError( message, status, body?, details?): ShopkitApiError; ``` ###### Parameters | Parameter | Type | Description | | - | - | - | | `message` | `string` | - | | `status` | `number` | - | | `body?` | `unknown` | Parsed response body when it was JSON, else the raw text, else null. | | `details?` | `unknown` | `details` / `context` from the platform's error envelope, when present. | ###### Returns [`ShopkitApiError`](#shopkitapierror) ###### Overrides [`ShopkitError`](#shopkiterror).[`constructor`](#constructor-14) #### Properties ##### body ```ts theme={null} readonly body: unknown; ``` Parsed response body when it was JSON, else the raw text, else null. ##### details ```ts theme={null} readonly details: unknown; ``` `details` / `context` from the platform's error envelope, when present. ##### status ```ts theme={null} readonly status: number; ``` #### Accessors ##### retryable ###### Get Signature ```ts theme={null} get retryable(): boolean; ``` True for the statuses where retrying the same request can plausibly help. ###### Returns `boolean` #### Methods ##### fromResponse() ```ts theme={null} static fromResponse(response, fallbackMessage): Promise; ``` ###### Parameters | Parameter | Type | | - | - | | `response` | `Response` | | `fallbackMessage` | `string` | ###### Returns `Promise`\<[`ShopkitApiError`](#shopkitapierror)> *** ### ShopkitClient A configured Quickbutik storefront client. One instance is cheap and stateless apart from the remembered ids (cart, checkout session, the cart's store id), so create one per request on the server (the cookie accessor belongs to that request) and one per app in the browser. #### Constructors ##### Constructor ```ts theme={null} new ShopkitClient(config): ShopkitClient; ``` ###### Parameters | Parameter | Type | | - | - | | `config` | [`ShopkitConfig`](#shopkitconfig) | ###### Returns [`ShopkitClient`](#shopkitclient) #### Properties ##### cart ```ts theme={null} readonly cart: CartResource; ``` ##### categories ```ts theme={null} readonly categories: CategoriesResource; ``` ##### checkout ```ts theme={null} readonly checkout: CheckoutResource; ``` ##### consent ```ts theme={null} readonly consent: ConsentResource; ``` The shopper's cookie-consent decision, as this client's cookies carry it, and the settings (`revision`, `cookieName`) from the config. On a server: `await shopkit.consent.read()`, handed to `` as `consent={{ initialState }}` so the banner is right on the first paint. ##### products ```ts theme={null} readonly products: ProductsResource; ``` ##### runtime ```ts theme={null} readonly runtime: ShopkitRuntimeInfo; ``` ##### scopes ```ts theme={null} readonly scopes: ScopeGuard; ``` ##### shop ```ts theme={null} readonly shop: ShopResource; ``` ##### shopPrefix ```ts theme={null} readonly shopPrefix: string; ``` The shop's storage prefix (`101928Y`), decoded from the publishable key. It is the folder the shop's files live under on the CDN — `https://cdn.quickbutik.com/images//products/` — and the value to build an `imageBaseUrl` from. It is NOT the shop's numeric id: the hosted checkout URL wants that one, and it is `Cart.storeId` (`checkout.start()` reads it from the cart for you). ##### storefront ```ts theme={null} readonly storefront: StorefrontBinding | null; ``` The campaign storefront this client sells into, with the surface defaulted — or null for an ordinary shop client. Set via `ShopkitConfig.storefront`. #### Accessors ##### apiUrl ###### Get Signature ```ts theme={null} get apiUrl(): string; ``` The commerce API origin this client talks to. ###### Returns `string` ##### checkoutUrl ###### Get Signature ```ts theme={null} get checkoutUrl(): string; ``` The hosted checkout origin shoppers are handed off to. ###### Returns `string` ##### currency ###### Get Signature ```ts theme={null} get currency(): string | null; ``` The currency this client browses in — the shopper's remembered choice, else `ShopkitConfig.currency`, else null (the shop's own currency). It is what is REQUESTED, not necessarily what comes back: a currency the shop does not offer falls back to the shop's, so format prices with `product.currency` / `cart.currency`, and use `describeCurrency()` with `shop.get()` to know the mode. Synchronous: answered from memory, or from storage when the adapter can answer synchronously (memory, `localStorage`, cookies, a request cookie jar). With an async-only adapter (Next's `cookies()`) this reads the configured default; requests still consult the adapter. ###### Returns `string` | `null` ##### defaultCurrency ###### Get Signature ```ts theme={null} get defaultCurrency(): string | null; ``` The `currency` this client was configured with, ignoring any choice. ###### Returns `string` | `null` ##### imageBaseUrl ###### Get Signature ```ts theme={null} get imageBaseUrl(): string | null; ``` Fallback image base, or null when images are rendered from the absolute `url` the API sends (the normal case). See `ShopkitConfig.imageBaseUrl`. ###### Returns `string` | `null` ##### shopId ###### Get Signature ```ts theme={null} get shopId(): string; ``` ###### Deprecated Renamed to [shopPrefix](#shopprefix) in 1.0.0-beta.4, because that is what the value is: the shop's storage prefix from the key. It is NOT the numeric id the hosted checkout needs — for that use `cart.storeId`, or let `checkout.start()` read it from the cart. Removed before 1.0.0. ###### Returns `string` ##### storage ###### Get Signature ```ts theme={null} get storage(): StorageAdapter; ``` The underlying storage adapter, for tests and for advanced integrations. ###### Returns [`StorageAdapter`](#storageadapter) #### Methods ##### onCurrencyChange() ```ts theme={null} onCurrencyChange(listener): () => void; ``` Be told when [currency](#currency) changes through `setCurrency()`. Returns an unsubscribe function. The React hooks and the custom elements use this to refetch prices and refresh the cart. ###### Parameters | Parameter | Type | | - | - | | `listener` | (`currency`) => `void` | ###### Returns ```ts theme={null} (): void; ``` ###### Returns `void` ##### setCurrency() ```ts theme={null} setCurrency(currency): Promise; ``` Browse in another currency: remember it, and notify [onCurrencyChange](#oncurrencychange) subscribers so a UI can refetch. ```ts theme={null} await shopkit.setCurrency("EUR") // every read and checkout now asks for EUR await shopkit.setCurrency(null) // back to the default ``` The cart is unchanged — it is priced per request, so the same cart reads in the new currency next time. Throws a `ShopkitConfigError` for a value that is not a three-letter code; a code the shop does not offer is accepted and simply resolves to the shop's currency server-side. ###### Parameters | Parameter | Type | | - | - | | `currency` | `string` \| `null` | ###### Returns `Promise`\<`void`> ##### withStorage() ```ts theme={null} withStorage(storage): ShopkitClient; ``` A copy of this client bound to different storage — the idiomatic way to reuse one long-lived configuration across many server requests, each with its own cookie jar. ```ts theme={null} const base = { publishableKey, apiUrl } export function shopkitForRequest(request: Request) { return createShopkitClient(base).withStorage( createRequestCookieStorage(request), ) } ``` ###### Parameters | Parameter | Type | | - | - | | `storage` | [`StorageAdapter`](#storageadapter) | ###### Returns [`ShopkitClient`](#shopkitclient) *** ### ShopkitConfigError A bad `createShopkitClient` config — a malformed key, a missing apiUrl. #### Extends * [`ShopkitError`](#shopkiterror) #### Constructors ##### Constructor ```ts theme={null} new ShopkitConfigError(message): ShopkitConfigError; ``` ###### Parameters | Parameter | Type | | - | - | | `message` | `string` | ###### Returns [`ShopkitConfigError`](#shopkitconfigerror) ###### Overrides [`ShopkitError`](#shopkiterror).[`constructor`](#constructor-14) *** ### ShopkitError Base class for everything shopkit throws, so `catch` can narrow on one type. #### Extends * `Error` #### Extended by * [`ShopkitApiError`](#shopkitapierror) * [`ShopkitConfigError`](#shopkitconfigerror) * [`ShopkitNetworkError`](#shopkitnetworkerror) * [`ShopkitScopeError`](#shopkitscopeerror) #### Constructors ##### Constructor ```ts theme={null} new ShopkitError(message): ShopkitError; ``` ###### Parameters | Parameter | Type | | - | - | | `message` | `string` | ###### Returns [`ShopkitError`](#shopkiterror) ###### Overrides ```ts theme={null} Error.constructor ``` *** ### ShopkitNetworkError The request never produced a response (offline, DNS, abort, timeout). #### Extends * [`ShopkitError`](#shopkiterror) #### Constructors ##### Constructor ```ts theme={null} new ShopkitNetworkError(message, cause): ShopkitNetworkError; ``` ###### Parameters | Parameter | Type | | - | - | | `message` | `string` | | `cause` | `unknown` | ###### Returns [`ShopkitNetworkError`](#shopkitnetworkerror) ###### Overrides [`ShopkitError`](#shopkiterror).[`constructor`](#constructor-14) #### Properties ##### cause ```ts theme={null} readonly cause: unknown; ``` ###### Overrides ```ts theme={null} ShopkitError.cause ``` *** ### ShopkitScopeError A call was made that the client's declared scopes do not cover. Thrown locally, BEFORE the request goes out, so the developer sees the missing scope by name instead of an opaque 403 from the gateway. #### Extends * [`ShopkitError`](#shopkiterror) #### Constructors ##### Constructor ```ts theme={null} new ShopkitScopeError( required, declared, operation): ShopkitScopeError; ``` ###### Parameters | Parameter | Type | | - | - | | `required` | `string` | | `declared` | readonly `string`\[] | | `operation` | `string` | ###### Returns [`ShopkitScopeError`](#shopkitscopeerror) ###### Overrides [`ShopkitError`](#shopkiterror).[`constructor`](#constructor-14) #### Properties ##### declared ```ts theme={null} readonly declared: readonly string[]; ``` ##### required ```ts theme={null} readonly required: string; ``` *** ### ShopResource Shop-level presentation data: name, logo, brand colour, default language, terms link. Everything a storefront shell needs before it renders. #### Constructors ##### Constructor ```ts theme={null} new ShopResource(transport, scopes): ShopResource; ``` ###### Parameters | Parameter | Type | | - | - | | `transport` | [`Transport`](#transport) | | `scopes` | [`ScopeGuard`](#scopeguard) | ###### Returns [`ShopResource`](#shopresource) #### Methods ##### get() ```ts theme={null} get(options?): Promise; ``` Served by the checkout's shop endpoint — the only shop surface a publishable key can reach, hence the `checkout:read` scope for what looks like plain branding. ###### Parameters | Parameter | Type | | - | - | | `options?` | [`RequestOptions`](#requestoptions) | ###### Returns `Promise`\<[`Shop`](#shop-2)> *** ### Transport The one place a request to Quickbutik is made. A thin adapter over `@quickbutik/sdk-gateway`, the platform's own API client, which is *bundled into* this package rather than depended on — it is published to a private registry, so a third-party storefront could not install it. Everything underneath comes from there: bearer auth derived from the publishable key, the `QB-Version` header, per-attempt timeouts, exponential-backoff retries that honour `Retry-After`, adaptive rate-limit pacing driven by the gateway's `X-RateLimit-*` headers, and an automatic `Idempotency-Key` on every mutation (so a retried `POST /cart` can never create two carts). shopkit behaves like every other Quickbutik client instead of re-implementing all of that. What stays here is shopkit's own contract: mapping the platform's error taxonomy onto shopkit's, treating a vanished resource as `null`, unwrapping api-core's response envelope, and adopting a rotated publishable key. #### Constructors ##### Constructor ```ts theme={null} new Transport(config): Transport; ``` ###### Parameters | Parameter | Type | | - | - | | `config` | [`ResolvedShopkitConfig`](#resolvedshopkitconfig) | ###### Returns [`Transport`](#transport) #### Methods ##### request() ```ts theme={null} request(request): Promise; ``` Send a request and return its body with any envelope removed. ###### Type Parameters | Type Parameter | | - | | `T` | ###### Parameters | Parameter | Type | | - | - | | `request` | [`TransportRequest`](#transportrequest-2) | ###### Returns `Promise`\<`T`> ##### requestOrNull() ```ts theme={null} requestOrNull(request): Promise; ``` Like [request](#requestornull-1) but resolves to null on 404/410 instead of throwing — "not there" is a normal answer for a remembered id (a cart that expired, a session that was cleaned up), not an error a storefront should crash on. ###### Type Parameters | Type Parameter | | - | | `T` | ###### Parameters | Parameter | Type | | - | - | | `request` | [`TransportRequest`](#transportrequest-2) | ###### Returns `Promise`\<`T` | `null`> ##### requestVoid() ```ts theme={null} requestVoid(request): Promise; ``` Send a request whose response body is discarded (204 / plain OK). ###### Parameters | Parameter | Type | | - | - | | `request` | [`TransportRequest`](#transportrequest-2) | ###### Returns `Promise`\<`void`> ## Interfaces ### AddCartItemInput #### Properties | Property | Type | Description | | - | - | - | | `productId` | `string` \| `number` | Either the prefixed id from `products.list()` (`"prod_123"`) or the raw numeric id. Both work — the gateway normalizes. | | `quantity?` | `number` | Defaults to 1. | | `variantId?` | `number` | Required for a product that has more than one variant. | *** ### AnalyticsContext What the hub knows when it calls a destination. #### Properties | Property | Type | Description | | - | - | - | | `currency?` | `string` | The default currency for events that carry none. | | `storeId` | `string` \| `null` | The shop's numeric store id when known (the hub's `storeId` option, else learned from the attached cart), null until then. The purchase eventID is built from it. | *** ### AnalyticsDestination Where events go. The kit ships Google (gtag.js / GTM) and the Meta Pixel; anything else — TikTok, Klaviyo, a server-side collector — is one object that implements this. ```ts theme={null} const tiktok: AnalyticsDestination = { id: "tiktok", requires: "marketing", // nothing happens before marketing consent load() { … inject the pixel … }, track(event) { if (event.name === "view_item") ttq.track("ViewContent", …) }, } ``` #### Properties | Property | Type | Description | | | - | - | - | - | | `id` | `string` | Stable, unique per hub. Used for the `[data-qb-analytics]` tag and in warnings. | | | `key?` | `string` | Which vendor account this instance reports to, as a string: two destinations with the same `key` are the same destination. A provider whose `destinations` are an inline array (new objects on every render) keeps the one it has while the key stays, and swaps it when the key changes. The built-in destinations use their ids only (\`google:G-X | …`, `meta:123\`), so changing another option on the same ids needs a remount; without a key the object itself is the identity. | | `requires` | [`ConsentCategory`](#consentcategory) \| `null` | The consent category this destination needs before it receives anything — `load()` included. `null` means it is always loaded and always receives events, and is expected to gate itself (the Google destination does, through Consent Mode). | | #### Methods ##### load()? ```ts theme={null} optional load(context): void; ``` Put the vendor's script on the page. Called once, the first time the destination is allowed, and only in a browser. Must be idempotent: a second hub on the same page (two ``s) calls it again. ###### Parameters | Parameter | Type | | - | - | | `context` | [`AnalyticsContext`](#analyticscontext) | ###### Returns `void` ##### onConsent()? ```ts theme={null} optional onConsent(state, context): void; ``` The decision changed. Called after `load()`, on every change, allowed or not. ###### Parameters | Parameter | Type | | - | - | | `state` | [`ConsentState`](#consentstate-1) \| `null` | | `context` | [`AnalyticsContext`](#analyticscontext) | ###### Returns `void` ##### track() ```ts theme={null} track(event, context): void; ``` ###### Parameters | Parameter | Type | | - | - | | `event` | [`CommerceEvent`](#commerceevent) | | `context` | [`AnalyticsContext`](#analyticscontext) | ###### Returns `void` ##### trackPurchase()? ```ts theme={null} optional trackPurchase( purchase, meta, context): void; ``` The purchase, with the id Meta and the platform dedupe it by (`purchase_{storeId}_{orderNumber}`). Optional: a destination without it receives the purchase through `track()` as a `purchase` event instead. ###### Parameters | Parameter | Type | | - | - | | `purchase` | [`PurchaseEvent`](#purchaseevent) | | `meta` | \{ `eventId`: `string`; } | | `meta.eventId` | `string` | | `context` | [`AnalyticsContext`](#analyticscontext) | ###### Returns `void` *** ### AnalyticsOptions #### Properties | Property | Type | Description | | - | - | - | | `bufferSize?` | `number` | How many events are remembered for destinations that cannot receive them yet (consent pending, vendor config still loading). Default 50, never fewer than 1: delivery itself reads from this memory, so a hub that remembered nothing would deliver nothing. | | `currency?` | `string` | The currency for events that carry none. Falls back to the cart's. | | `debug?` | `boolean` | Log every dispatch to the console. | | `destinations?` | [`AnalyticsDestination`](#analyticsdestination)\[] | Where events go. More can be added later with `addDestination`. | | `requireConsent?` | `boolean` | False runs every destination ungated — the hosted storefront's behaviour for a shop without the consent app. For a storefront that is certain it owes its shoppers no consent. Default true. | | `storeId?` | `string` \| `number` \| `null` | The shop's numeric store id, for the purchase dedup key and Meta eventID. Falls back to the id on the attached cart (`Cart.storeId`), which is how the React provider and the elements learn it. | *** ### ApiEnvelope api-core wraps most responses in this envelope. The gateway strips it on some routes and forwards it on others, so the transport unwraps defensively rather than per-route (see `unwrapEnvelope`). #### Type Parameters | Type Parameter | | - | | `T` | #### Properties | Property | Type | | - | - | | `data?` | `T` | | `error?` | `string` | | `message?` | `string` | | `statusCode?` | `number` | *** ### AsyncSnapshot #### Type Parameters | Type Parameter | | - | | `T` | #### Properties | Property | Type | Description | | - | - | - | | `data` | `T` \| `null` | - | | `error` | `Error` \| `null` | - | | `loading` | `boolean` | True while a request is in flight, including a refetch over stale data. | | `status` | [`AsyncStatus`](#asyncstatus) | - | *** ### Cart A server-owned cart. Prices are recomputed on every read, so a cart held in a cookie for a week still reflects today's prices — never cache these numbers client-side beyond the current render. #### Properties | Property | Type | Description | | - | - | - | | `createdAt` | `string` | - | | `currency` | `string` | The currency every amount in THIS response is in. A cart stores no currency of its own: it is priced per request, in the client's chosen currency when the shop offers it, so the same cart reads in SEK on one request and EUR on the next. | | `id` | `string` | - | | `itemCount` | `number` | Sum of quantities, not of lines. | | `items` | [`CartItem`](#cartitem)\[] | - | | `presentment?` | [`CartPresentment`](#cartpresentment-1) | How this response's currency relates to the checkout. Absent from a platform older than the field — read it as `mode: "base"`. | | `storefrontId?` | `string` \| `null` | The campaign storefront this cart is bound to, or null for an ordinary cart. A bound cart is priced with the campaign's overrides on every read, and a checkout session created from it inherits the binding. Absent from a platform older than the field — read it as null. | | `storeId` | `number` | - | | `subtotal` | `number` | - | | `subtotalExclTax` | `number` | - | | `subtotalInclTax` | `number` | - | | `surface?` | `"embed"` \| `"link"` \| `"hosted"` \| `"shopkit"` \| `"agentic"` \| `null` | Where the campaign was presented, recorded with the binding. | | `total` | `number` | - | | `totalDiscount` | `number` | - | | `totalExclTax` | `number` | - | | `totalInclTax` | `number` | - | | `totalTax` | `number` | - | | `updatedAt` | `string` | - | *** ### CartItem #### Properties | Property | Type | Description | | - | - | - | | `available` | `boolean` | False when the product was hidden or deleted after being added. | | `compareAtPrice` | `number` \| `null` | - | | `discountAmount` | `number` | - | | `id` | `string` | Cart line id (uuid) — the handle for update/remove, NOT the product id. | | `imageUrl` | `string` \| `null` | - | | `lineTotal` | `number` | - | | `lineTotalExclTax` | `number` | - | | `lineTotalInclTax` | `number` | - | | `lineTotalTax` | `number` | - | | `productId` | `number` | - | | `productTitle` | `string` \| `null` | - | | `quantity` | `number` | - | | `sku` | `string` \| `null` | - | | `taxAmount` | `number` | - | | `taxRate` | `number` | - | | `unitPrice` | `number` | Display unit price — incl. or excl. tax depending on the shop's setting. | | `unitPriceExclTax` | `number` | - | | `unitPriceInclTax` | `number` | - | | `variantId?` | `number` | - | | `variantName` | `string` \| `null` | "Red / XL", built from the variant's option values. Null for simple products. | *** ### CartLineDiff #### Properties | Property | Type | | - | - | | `added` | [`CommerceItem`](#commerceitem)\[] | | `currency?` | `string` | | `removed` | [`CommerceItem`](#commerceitem)\[] | *** ### CartMutationEvent A successful change made THROUGH this store, with the cart before and after — what an analytics layer diffs into `add_to_cart` / `remove_from_cart`. Never emitted for `load`, `refresh` or `hydrate` (nothing changed, something was read) nor for a failed mutation. #### Properties | Property | Type | | - | - | | `after` | [`Cart`](#cart-1) \| `null` | | `before` | [`Cart`](#cart-1) \| `null` | | `type` | `"add"` \| `"update"` \| `"remove"` \| `"clear"` \| `"buy-now"` | *** ### CartPresentment See [Cart.presentment](#presentment). #### Properties | Property | Type | Description | | - | - | - | | `baseCurrency` | `string` | The shop's own currency. | | `chargeCurrency` | `string` | What the checkout will charge in. | | `exchangeRate` | `number` | Units of `currency` per 1 unit of `baseCurrency`. 1 for `"base"`. | | `mode` | [`ShopCurrencyMode`](#shopcurrencymode-1) | - `"base"` — amounts are in the shop's own currency. - `"display"` — amounts are converted for display; the checkout charges `chargeCurrency` (the shop's currency). - `"charge"` — amounts are what the checkout will charge, in `currency`. | *** ### Category #### Properties | Property | Type | Description | | - | - | - | | `ancestors` | [`CategoryAncestor`](#categoryancestor)\[] | Ancestors ordered root to immediate parent. Empty for a top-level category. | | `childCount` | `number` | - | | `description` | `string` \| `null` | - | | `description1` | `string` \| `null` | - | | `description2` | `string` \| `null` | - | | `id` | `string` | Prefixed id (`cat_12`). | | `image` | `string` \| `null` | The bare storage filename of the cover image. Not a URL — see [Category.imageUrl](#imageurl-1). | | `imageUrl` | `string` \| `null` | Absolute URL of the cover image, with no resize parameters. Null when the category has no image. Resolve it with `resolveCategoryImageUrl`. | | `name` | `string` \| `null` | - | | `parentId` | `string` \| `null` | - | | `path` | `string` \| `null` | Full slug path, e.g. `clothing/shirts`. | | `seoTitle` | `string` \| `null` | - | | `slug` | `string` \| `null` | - | *** ### CategoryAncestor One entry of [Category.ancestors](#ancestors): a lightweight parent reference. #### Properties | Property | Type | Description | | - | - | - | | `id` | `string` | Prefixed id (`cat_2`). | | `name` | `string` \| `null` | - | | `slug` | `string` \| `null` | The ancestor's own slug segment, not its full path. | *** ### CategoryListParams #### Properties | Property | Type | Description | | - | - | - | | `cursor?` | `string` | - | | `limit?` | `number` | - | | `parentId?` | `string` | - | | `root?` | `boolean` | Only top-level categories. | | `search?` | `string` | - | *** ### CheckoutCartProduct A cart line as the checkout session snapshotted it. #### Properties | Property | Type | | - | - | | `imageUrl` | `string` \| `null` | | `name` | `string` | | `price` | `number` | | `productId` | `string` | | `quantity` | `number` | | `variantId?` | `string` | | `variantName?` | `string` \| `null` | | `weight?` | `number` \| `null` | *** ### CheckoutDataNodes The data nodes shopkit types; the map carries others too. #### Properties | Property | Type | | - | - | | `cart_products` | [`CheckoutCartProduct`](#checkoutcartproduct)\[] | | `discount` | [`OrderLine`](#orderline)\[] | | `order_total` | [`CheckoutOrderTotal`](#checkoutordertotal) | | `payment_cost` | [`OrderLine`](#orderline)\[] | | `pricing` | [`CheckoutPricing`](#checkoutpricing) | | `promocode` | [`OrderLine`](#orderline)\[] | | `shipping_cost` | [`OrderLine`](#orderline)\[] | *** ### CheckoutOrderTotal The server-authoritative total: products + shipping + payment fee + discounts. This is the figure the shopper is charged — never recompute it. #### Properties | Property | Type | | - | - | | `currency` | `string` | | `lines` | [`OrderLine`](#orderline)\[] | | `subtotal` | `number` | | `subtotalExclTax` | `number` | | `subtotalInclTax` | `number` | | `total` | `number` | | `totalDiscount` | `number` | | `totalPaymentFee` | `number` | | `totalShipping` | `number` | | `totalTax` | `number` | *** ### CheckoutPricing Product-only subtotals. `order_total` is the one that includes everything. #### Properties | Property | Type | Description | | - | - | - | | `baseCurrency?` | `string` | The shop's own currency, when the session is charged in another one. | | `currency` | `string` | The currency the session is priced AND charged in. | | `exchangeRate?` | `number` | Units of `currency` per 1 unit of `baseCurrency`, when they differ. | | `subtotal` | `number` | - | | `subtotalExclTax` | `number` | - | | `subtotalInclTax` | `number` | - | | `taxOnTop?` | `boolean` | Shop prices are ex-VAT and tax is added on top. Absent → false. | | `totalTax` | `number` | - | *** ### CheckoutSession What `POST /v2/checkout/sessions` answers with. #### Extended by * [`V2Handoff`](#v2handoff) #### Properties | Property | Type | Description | | - | - | - | | `backUrl` | `string` \| `null` | - | | `cancelUrl` | `string` \| `null` | - | | `cartId` | `string` | - | | `data` | [`SessionDataMap`](#sessiondatamap) | - | | `displayCurrency?` | [`DisplayCurrency`](#displaycurrency-2) \| `null` | The currency the checkout shows an approximate amount in, or null when none applies (no currency sent, the shop's own currency, or a `"charge"` currency — then `data.pricing.value.currency` is it). Absent on older platforms. | | `embed?` | [`SessionEmbed`](#sessionembed) \| `null` | The embed permission recorded at creation, or null when there is none. | | `fields` | [`SessionFieldMap`](#sessionfieldmap) | - | | `language` | `string` \| `null` | - | | `origin` | `string` \| `null` | `"storefront-native"` only for the built-in storefront; null for headless. | | `sessionId` | `string` | - | | `storefrontId?` | `string` \| `null` | The campaign storefront the session is bound to, or null. Absent on older platforms. | | `successMode?` | `"redirect"` \| `"inline"` | How this checkout ends, as the platform echoes it. Missing means `"redirect"`. | | `successUrl` | `string` \| `null` | The success URL the session was created with, or null when the session was created in inline mode without a successUrl. | | `surface?` | `"embed"` \| `"link"` \| `"hosted"` \| `"shopkit"` \| `"agentic"` \| `null` | - | | `theme` | `"light"` \| `"dark"` | The theme this checkout is painted in — always `"light"` or `"dark"`, never absent. This is the answer, not an echo: it is what you asked for when you asked for something, and the merchant's shop-wide choice when you did not. You cannot tell the two apart from here, and you do not need to — this is what the shopper sees. | *** ### CheckoutSessionSnapshot What `GET /v2/checkout/sessions/:id` answers with. #### Properties | Property | Type | Description | | - | - | - | | `backUrl` | `string` \| `null` | - | | `blockingFields` | `string`\[] | Names of the fields still standing between the shopper and payment. | | `cancelUrl` | `string` \| `null` | - | | `cartId` | `string` \| `null` | - | | `data` | [`SessionDataMap`](#sessiondatamap) | - | | `displayCurrency?` | [`DisplayCurrency`](#displaycurrency-2) \| `null` | See [CheckoutSession.displayCurrency](#displaycurrency). | | `embed?` | [`SessionEmbed`](#sessionembed) \| `null` | The embed permission recorded at creation, or null when there is none. | | `fields` | [`SessionFieldMap`](#sessionfieldmap) | - | | `isComplete` | `boolean` | True when every required field is valid — the checkout can take payment. | | `language` | `string` \| `null` | - | | `origin` | `string` \| `null` | - | | `storefrontId?` | `string` \| `null` | The campaign storefront the session is bound to, or null. Absent on older platforms. | | `successMode?` | `"redirect"` \| `"inline"` | How this checkout ends, as the platform echoes it. Missing means `"redirect"`. | | `successUrl` | `string` \| `null` | The success URL the session was created with, or null when the session was created in inline mode without a successUrl. | | `surface?` | `"embed"` \| `"link"` \| `"hosted"` \| `"shopkit"` \| `"agentic"` \| `null` | - | *** ### CommerceEvent #### Properties | Property | Type | | - | - | | `name` | [`CommerceEventName`](#commerceeventname-1) | | `params` | [`CommerceEventParams`](#commerceeventparams-1) | *** ### CommerceEventParams #### Indexable ```ts theme={null} [key: string]: unknown ``` #### Properties | Property | Type | Description | | - | - | - | | `currency?` | `string` | - | | `items?` | [`CommerceItem`](#commerceitem)\[] | - | | `value?` | `number` | Major units. | *** ### CommerceItem A GA4 item. `item_id` is the bare numeric PRODUCT id, never the variant's: it is what the hosted storefront's tags emit and what the Google Shopping feed carries, so it is the only id that matches a catalogue on the other end. The variant rides along as `item_variant`. Prices are in MAJOR units. #### Indexable ```ts theme={null} [key: string]: unknown ``` #### Properties | Property | Type | Description | | - | - | - | | `item_category?` | `string` | - | | `item_id` | `string` | - | | `item_name?` | `string` | - | | `item_variant?` | `string` | - | | `price?` | `number` | Unit price in major units (`99`, not `9900`). | | `quantity?` | `number` | - | *** ### ConsentChoice What a shopper chooses: the optional categories, on or off. #### Extended by * [`ConsentState`](#consentstate-1) #### Properties | Property | Type | | - | - | | `analytics` | `boolean` | | `marketing` | `boolean` | *** ### ConsentCookieOptions #### Extended by * [`ConsentCookieWriteOptions`](#consentcookiewriteoptions) #### Properties | Property | Type | Description | | - | - | - | | `cookieName?` | `string` | Defaults to `qb_consent`. | | `revision?` | `number` | The revision a stored decision must match to count. Defaults to 1. | *** ### ConsentCookieWriteOptions #### Extends * [`ConsentCookieOptions`](#consentcookieoptions) #### Extended by * [`ConsentStoreOptions`](#consentstoreoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `cookieName?` | `string` | Defaults to `qb_consent`. | [`ConsentCookieOptions`](#consentcookieoptions).[`cookieName`](#cookiename-1) | | `domain?` | `string` | Share the decision across subdomains (`.myshop.com`). Host-only by default. | - | | `maxAgeDays?` | `number` | Defaults to 180 days. | - | | `revision?` | `number` | The revision a stored decision must match to count. Defaults to 1. | [`ConsentCookieOptions`](#consentcookieoptions).[`revision`](#revision-2) | | `sameSite?` | `"lax"` \| `"strict"` \| `"none"` | Defaults to `lax`. | - | | `secure?` | `boolean` | Defaults to true on https origins, false otherwise (localhost works). | - | *** ### ConsentLabels The copy of the default banner, in the languages Quickbutik shops sell in. The kit renders no markup of its own except where an empty element would be a bug, and an empty consent banner is one — so `` and `` fill themselves with a minimal dialog when given no content, and this is its text. Every string is overridable; a storefront with its own voice passes `labels`. #### Properties | Property | Type | Description | | - | - | - | | `acceptAll` | `string` | - | | `analytics` | `string` | - | | `analyticsDescription` | `string` | - | | `close` | `string` | - | | `cookieSettings` | `string` | The footer button that reopens the banner (``). | | `description` | `string` | - | | `marketing` | `string` | - | | `marketingDescription` | `string` | - | | `necessary` | `string` | - | | `necessaryDescription` | `string` | - | | `privacyPolicy` | `string` | - | | `rejectAll` | `string` | - | | `save` | `string` | - | | `settings` | `string` | - | | `title` | `string` | - | *** ### ConsentModeSignals The four Google Consent Mode v2 signals the platform sets. The mapping is the hosted storefront's, byte for byte: `analytics` drives `analytics_storage`; `marketing` drives the three advertising signals. `functionality_storage` and `personalization_storage` are deliberately not set — the platform never has, and a storefront that wants them can push its own `gtag('consent', …)` call. #### Properties | Property | Type | | - | - | | `ad_personalization` | [`ConsentModeValue`](#consentmodevalue) | | `ad_storage` | [`ConsentModeValue`](#consentmodevalue) | | `ad_user_data` | [`ConsentModeValue`](#consentmodevalue) | | `analytics_storage` | [`ConsentModeValue`](#consentmodevalue) | *** ### ConsentSnapshot What the store exposes: the decision plus the one piece of UI state a banner and a far-away "Cookie settings" link have to share — whether the preferences panel is open. Not persisted. #### Extends * [`ConsentState`](#consentstate-1) #### Extended by * [`ConsentBannerState`](/kit/api/react#consentbannerstate) * [`UseConsentResult`](/kit/api/react#useconsentresult) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `analytics` | `boolean` | - | [`ConsentState`](#consentstate-1).[`analytics`](#analytics-4) | | `decidedAt` | `string` \| `null` | ISO 8601, when the shopper decided. Null while undecided. | [`ConsentState`](#consentstate-1).[`decidedAt`](#decidedat-1) | | `marketing` | `boolean` | - | [`ConsentState`](#consentstate-1).[`marketing`](#marketing-3) | | `open` | `boolean` | - | - | | `revision` | `number` | The policy revision the decision was made against. Bump the configured revision when the cookie policy changes materially and every shopper is asked again; a stored decision for an older revision reads as undecided. | [`ConsentState`](#consentstate-1).[`revision`](#revision-5) | | `status` | [`ConsentStatus`](#consentstatus) | - | [`ConsentState`](#consentstate-1).[`status`](#status-3) | *** ### ConsentState The persisted decision. Both flags are `false` while `undecided`, so a consumer that only reads the flags gets the safe answer without checking the status first. #### Extends * [`ConsentChoice`](#consentchoice) #### Extended by * [`ConsentSnapshot`](#consentsnapshot) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `analytics` | `boolean` | - | [`ConsentChoice`](#consentchoice).[`analytics`](#analytics-1) | | `decidedAt` | `string` \| `null` | ISO 8601, when the shopper decided. Null while undecided. | - | | `marketing` | `boolean` | - | [`ConsentChoice`](#consentchoice).[`marketing`](#marketing) | | `revision` | `number` | The policy revision the decision was made against. Bump the configured revision when the cookie policy changes materially and every shopper is asked again; a stored decision for an older revision reads as undecided. | - | | `status` | [`ConsentStatus`](#consentstatus) | - | - | *** ### ConsentStoreOptions #### Extends * [`ConsentCookieWriteOptions`](#consentcookiewriteoptions) #### Extended by * [`ConsentProviderProps`](/kit/api/react#consentproviderprops) * [`ElementsConsentOptions`](/kit/api/elements#elementsconsentoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `cookieName?` | `string` | Defaults to `qb_consent`. | [`ConsentCookieWriteOptions`](#consentcookiewriteoptions).[`cookieName`](#cookiename-2) | | `domain?` | `string` | Share the decision across subdomains (`.myshop.com`). Host-only by default. | [`ConsentCookieWriteOptions`](#consentcookiewriteoptions).[`domain`](#domain) | | `initialState?` | [`ConsentState`](#consentstate-1) \| `null` | The state to start from, instead of reading the cookie. For a server render: `readConsentCookie(cookieHeader)` on the server, passed down, so the first paint already knows the decision. Also what a test uses. `null` means "start undecided, do not read the cookie". | - | | `maxAgeDays?` | `number` | Defaults to 180 days. | [`ConsentCookieWriteOptions`](#consentcookiewriteoptions).[`maxAgeDays`](#maxagedays) | | `persist?` | `boolean` | Write the decision to the cookie. Default true. Set false when another system owns persistence — a third-party consent platform whose callback calls `save()` on this store, or a test. | - | | `revision?` | `number` | The revision a stored decision must match to count. Defaults to 1. | [`ConsentCookieWriteOptions`](#consentcookiewriteoptions).[`revision`](#revision-3) | | `sameSite?` | `"lax"` \| `"strict"` \| `"none"` | Defaults to `lax`. | [`ConsentCookieWriteOptions`](#consentcookiewriteoptions).[`sameSite`](#samesite) | | `secure?` | `boolean` | Defaults to true on https origins, false otherwise (localhost works). | [`ConsentCookieWriteOptions`](#consentcookiewriteoptions).[`secure`](#secure) | *** ### CookieAccessor The three cookie operations shopkit needs from a server framework. Model it on whatever the host gives you — Next's `cookies()`, a Hono context, an Express `req`/`res` pair. `set`/`remove` are optional: a read-only accessor (an RSC, which cannot mutate cookies) is a legitimate, common case. Writes are then dropped rather than throwing, so rendering a server component never crashes just because it touched the cart. #### Methods ##### get() ```ts theme={null} get(name): MaybePromise; ``` ###### Parameters | Parameter | Type | | - | - | | `name` | `string` | ###### Returns [`MaybePromise`](#maybepromise)\<`string` | `null` | `undefined`> ##### getAll()? ```ts theme={null} optional getAll(): MaybePromise; ``` Every cookie on the request, as Next's `cookies().getAll()` returns them. Optional, and read by one feature only: the checkout handoff looks for Google Analytics' `_ga` / `_ga_` cookies (whose names it cannot know in advance) to stitch the storefront's GA session to the hosted checkout's. Without it the consent decision is still forwarded and the GA ids are not. ###### Returns [`MaybePromise`](#maybepromise)\ ##### remove()? ```ts theme={null} optional remove(name, attributes): MaybePromise; ``` ###### Parameters | Parameter | Type | | - | - | | `name` | `string` | | `attributes` | [`CookieAttributes`](#cookieattributes) | ###### Returns [`MaybePromise`](#maybepromise)\<`void`> ##### set()? ```ts theme={null} optional set( name, value, attributes): MaybePromise; ``` ###### Parameters | Parameter | Type | | - | - | | `name` | `string` | | `value` | `string` | | `attributes` | [`CookieAttributes`](#cookieattributes) | ###### Returns [`MaybePromise`](#maybepromise)\<`void`> *** ### CookieAttributes Cookie primitives with no dependencies, usable on both sides of the wire. Kept deliberately small: shopkit only ever stores two opaque ids (the cart id and the checkout session id), so there is no need for signing, chunking or the full `cookie` package. #### Properties | Property | Type | Description | | - | - | - | | `domain?` | `string` | - | | `httpOnly?` | `boolean` | Cookies written from the browser can never be httpOnly (the browser has no way to set it), so this only has meaning for a server-side adapter. | | `maxAge?` | `number` | Seconds. Omitted → session cookie. | | `path?` | `string` | Defaults to `/` so the id is visible to every route of the storefront. | | `sameSite?` | `"lax"` \| `"strict"` \| `"none"` | Defaults to `lax` — the shopper returns from the hosted checkout via a top-level GET navigation, which `lax` allows and `strict` would drop. | | `secure?` | `boolean` | Defaults to true on https origins, false otherwise (so localhost works). | *** ### CreateSessionInput Input to `checkout.createSession()`. `successUrl` is REQUIRED unless `successMode` is `"inline"`; a redirect session without one throws a `ShopkitConfigError` before any request. `successMode` is sent only when set. #### Properties | Property | Type | Description | | - | - | - | | `backUrl?` | `string` | Where the hosted checkout's "back to shop" / "continue shopping" links point — the header logo and back arrow, the empty-cart screen and the order confirmation. Same URL rule as `successUrl`: any `https` host, `http` only for `localhost`/loopback. When omitted the checkout falls back to the shop's storefront URL, then to the origin of `successUrl` — which for a headless storefront is usually the right page anyway. Set it when your storefront lives on a path or you want a specific landing page. In `inline` success mode it is the ONLY way home from the confirmation, so a headless or campaign storefront should set it to the page the shopper came from. | | `cancelUrl?` | `string` | Where "back to cart" goes. | | `cartId` | `string` | The cart to check out. | | `currency?` | `string` \| `null` | The currency the shopper is browsing in. Defaults to the client's currency (`client.currency`); pass `null` to send none. The shop decides what happens with it, exactly as for product and cart reads: a `"display"` currency leaves the session in the shop's currency and the response carries it as [CheckoutSession.displayCurrency](#displaycurrency); a `"charge"` currency prices and charges the session in it; anything else has no effect. Fixed when the session is created — a session for the same cart in a different currency is a new session. checkout-v2 only. | | `embed?` | [`SessionEmbed`](#sessionembed) | Declare where this session may be framed. Required for an embedded checkout and ignored by the redirect one — see [SessionEmbed](#sessionembed). | | `language?` | `string` | Checkout UI language ("sv", "en", "en-US"). Validation is lenient — a code the checkout cannot translate falls back to the shop default rather than failing. | | `prefill?` | [`SessionPrefill`](#sessionprefill) | - | | `storefrontId?` | `string` | The campaign storefront this checkout is started from — `sf_…`. Binds the session to the campaign: its prices apply, it must be live, its quantity limits are enforced, and its id goes on the order. Falls back to the client's `storefront` binding; when neither is set the field is not sent, and a cart already bound to a campaign passes its binding on server-side. With an explicit `cartId` any campaign may be named. Without one (`checkout.start()` / `buyNow()` on the remembered cart) it must match the client's binding — see `StorefrontAttribution`. | | `successMode?` | `"redirect"` \| `"inline"` | `"redirect"` (the default when omitted) or `"inline"`. See [SuccessMode](#successmode-7). | | `successUrl?` | `string` | Where the shopper lands after paying. Required unless `successMode: "inline"`, where the checkout never redirects. Any `https` URL is accepted — the host needs no registration and no relationship to the shop's platform URL. `http` is accepted only for `localhost` and loopback addresses; a `javascript:` URL, or any other scheme, is rejected with 400. Only the ORIGIN is used for the post-payment redirect: the hosted checkout sends the shopper to `/success/?hash=…&t=…`, so mount a route there (see `parseReturnUrl`). | | `surface?` | `"embed"` \| `"link"` \| `"hosted"` \| `"shopkit"` \| `"agentic"` | Where the campaign was presented to this shopper. Only sent together with a `storefrontId`; defaults to the client's surface, then `"shopkit"`. | | `theme?` | `"light"` \| `"dark"` | Which theme the hosted checkout is painted in for this shopper. Set it when your own pages are dark, so the checkout does not flash white on the way in. Omitting it is not the same as passing `"light"`: omit it and the checkout follows the theme the merchant chose for their shop, pass `"light"` and this checkout stays light whatever the merchant chose. Fixed when the session is created and not changeable afterwards, so decide it with the rest of the page's theme. If you omit it, the merchant's choice applies live — a shopper with the checkout already open sees it change when the merchant changes it. | *** ### CurrencyInfo What a currency choice means for one shop. See [describeCurrency](#describecurrency). #### Extended by * [`UseCurrencyResult`](/kit/api/react#usecurrencyresult) #### Properties | Property | Type | Description | | - | - | - | | `baseCurrency` | `string` \| `null` | The shop's own (base) currency, or null when the shop is not known yet. | | `chargeCurrency` | `string` \| `null` | What the checkout will charge: the base currency, or `currency` in charge mode. | | `currencies` | [`ShopCurrency`](#shopcurrency-1)\[] | Every currency the shop offers, base first. Empty until the shop is known. | | `currency` | `string` \| `null` | The currency prices are shown in: the chosen code when the shop offers it, else the shop's own currency. Null only before the shop is known and with nothing chosen. | | `mode` | [`ShopCurrencyMode`](#shopcurrencymode-1) | - `"base"` — the shop's own currency; nothing is converted. - `"display"` — prices are SHOWN converted, and the checkout charges the shop's currency (with the converted amount as an approximation). - `"charge"` — priced and charged in `currency`. | | `rate` | `number` | Units of `currency` per 1 unit of the base currency. 1 for `"base"`. | *** ### DataState A server-computed value derived from the fields (prices, shipping options). #### Type Parameters | Type Parameter | Default type | | - | - | | `T` | `unknown` | #### Properties | Property | Type | | - | - | | `resolvedAt` | `string` \| `null` | | `value` | `T` \| `null` | *** ### DestinationsFromShopOptions #### Properties | Property | Type | Description | | - | - | - | | `google?` | `Omit`\<[`GoogleTagOptions`](#googletagoptions), `"ga4MeasurementId"` \| `"gtmContainerId"` \| `"adsConversionId"`> | Passed through to the Google destination. | | `loadBeforeConsent?` | `boolean` | Load GTM / gtag.js before a decision, in Consent Mode denied. Default false. Shorthand for `google: { loadBeforeConsent }`. | *** ### DisplayCurrency The currency a checkout may show an APPROXIMATE amount in, next to the real prices — set when the session was created with a `"display"` currency. #### Properties | Property | Type | Description | | - | - | - | | `code` | `string` | Upper-case ISO 4217. | | `rate` | `number` | Units of `code` per 1 unit of the currency the session is charged in. | *** ### EmbeddedCheckoutEventMap #### Properties | Property | Type | | - | - | | `complete` | `object` | | `complete.orderNumber` | `number` \| `null` | | `complete.sessionId` | `string` | | `complete.successUrl` | `string` \| `null` | | `demo-complete` | `object` | | `demo-complete.configureUrl` | `string` \| `null` | | `demo-complete.sessionId` | `string` | | `error` | `object` | | `error.code` | [`EmbedErrorCode`](#embederrorcode) | | `error.fatal` | `boolean` | | `error.message` | `string` | | `event` | `object` | | `event.name` | `string` | | `event.params` | `Record`\<`string`, `unknown`> | | `fallback` | `object` | | `fallback.reason` | [`EmbeddedCheckoutFallbackReason`](#embeddedcheckoutfallbackreason) | | `fallback.url` | `string` \| `null` | | `height` | `object` | | `height.height` | `number` | | `navigate` | `object` | | `navigate.reason` | [`EmbedNavigateReason`](#embednavigatereason) | | `navigate.url` | `string` | | `ready` | `object` | | `ready.sessionId` | `string` | | `ready.shopId` | `string` | | `ready.step` | [`EmbedStep`](#embedstep) | | `redirect` | `object` | | `redirect.data` | `Record`\<`string`, `string`> | | `redirect.method` | [`EmbedRedirectMethod`](#embedredirectmethod) | | `redirect.url` | `string` | | `scroll-to` | `object` | | `scroll-to.top` | `number` | | `step` | `object` | | `step.step` | [`EmbedStep`](#embedstep) | *** ### EmbeddedCheckoutInitEmbed Presentation and default-behaviour options, shared by `mount` and `resume`. #### Extends * [`EmbedRenderOptions`](#embedrenderoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `checkoutOrigin` | `string` | Origin of `url`; the only origin messages are accepted from or sent to. | - | | `confirmation?` | `"redirect"` \| `"inline"` | What happens when the order completes. - `"redirect"` (default) — leave the page for the confirmed order, at exactly the URL the redirect checkout would have sent the shopper to (`/success/?hash=…`), so one thank-you page serves both paths. - `"inline"` — stay on the page and let the frame render its own confirmation. | [`EmbedRenderOptions`](#embedrenderoptions).[`confirmation`](#confirmation-3) | | `container` | `Element` | The element the iframe is appended to. | - | | `fallbackRedirect?` | `boolean` | Navigate to the hosted checkout when there is nothing to frame, and when the frame that was built never answers. On by default — a shopper must never be left looking at an empty box because a shop is configured differently than the page assumed, or because this page is not the origin the session was created for. Turn it off to render your own message from the `fallback` event; its `url` is where the shopper should go. | [`EmbedRenderOptions`](#embedrenderoptions).[`fallbackRedirect`](#fallbackredirect-1) | | `fallbackUrl` | `string` \| `null` | The hosted (redirect) checkout URL for the same session — where the shopper is sent if the frame never answers. Null only when the caller has no way of knowing it, in which case the `handshake-timeout` fallback is reported but nobody is navigated anywhere. | - | | `handleNavigation?` | `boolean` | Perform the contract's default navigations (`navigate`, `redirect`, `complete`). Off means the handle only reports; YOU must then perform the redirect break-out yourself or redirect payment methods will not work. Defaults to on. | [`EmbedRenderOptions`](#embedrenderoptions).[`handleNavigation`](#handlenavigation-1) | | `handshakeTimeoutMs?` | `number` | Override the 15s handshake deadline. For tests, chiefly. | [`EmbedRenderOptions`](#embedrenderoptions).[`handshakeTimeoutMs`](#handshaketimeoutms-1) | | `minHeight?` | `number` | Height of the frame before the first `height` message, and the floor it never drops below. Set it to roughly the height of your checkout so the page does not jump on first paint. | [`EmbedRenderOptions`](#embedrenderoptions).[`minHeight`](#minheight-1) | | `mode` | `"embed"` | - | - | | `sessionId` | `string` \| `null` | - | - | | `successUrl?` | `string` \| `null` | Fallback landing for a completed order, used only when the server sent none. The server's own URL — `/success/?hash=…` — wins, because that is where the redirect checkout lands the same shopper. | - | | `title?` | `string` | The iframe's accessible name. Defaults to `"Checkout"`. | [`EmbedRenderOptions`](#embedrenderoptions).[`title`](#title-2) | | `url` | `string` | The `/embed/{shopId}/{sessionId}` URL. | - | *** ### EmbeddedCheckoutInitFallback #### Properties | Property | Type | Description | | - | - | - | | `mode` | `"fallback"` | - | | `reason` | [`EmbeddedCheckoutFallbackReason`](#embeddedcheckoutfallbackreason) | - | | `redirect` | `boolean` | Navigate to `url` after emitting. Off for a caller doing its own thing. | | `sessionId` | `string` \| `null` | - | | `url` | `string` \| `null` | The hosted (redirect) checkout URL, when there is one. | *** ### EmbedRenderOptions Presentation and default-behaviour options, shared by `mount` and `resume`. #### Extended by * [`EmbeddedCheckoutInitEmbed`](#embeddedcheckoutinitembed) * [`MountCheckoutInput`](#mountcheckoutinput) * [`ResumeCheckoutInput`](#resumecheckoutinput) #### Properties | Property | Type | Description | | - | - | - | | `confirmation?` | `"redirect"` \| `"inline"` | What happens when the order completes. - `"redirect"` (default) — leave the page for the confirmed order, at exactly the URL the redirect checkout would have sent the shopper to (`/success/?hash=…`), so one thank-you page serves both paths. - `"inline"` — stay on the page and let the frame render its own confirmation. | | `fallbackRedirect?` | `boolean` | Navigate to the hosted checkout when there is nothing to frame, and when the frame that was built never answers. On by default — a shopper must never be left looking at an empty box because a shop is configured differently than the page assumed, or because this page is not the origin the session was created for. Turn it off to render your own message from the `fallback` event; its `url` is where the shopper should go. | | `handleNavigation?` | `boolean` | Perform the contract's default navigations (`navigate`, `redirect`, `complete`). Off means the handle only reports; YOU must then perform the redirect break-out yourself or redirect payment methods will not work. Defaults to on. | | `handshakeTimeoutMs?` | `number` | Override the 15s handshake deadline. For tests, chiefly. | | `minHeight?` | `number` | Height of the frame before the first `height` message, and the floor it never drops below. Set it to roughly the height of your checkout so the page does not jump on first paint. | | `title?` | `string` | The iframe's accessible name. Defaults to `"Checkout"`. | *** ### EmbedViewport The host's visible region, as the frame needs to see it. This is what lets a modal or a 3-D Secure overlay position itself inside the visible slice of a 2000px-tall auto-sized frame instead of at the frame's own centre, which can be far off screen. #### Properties | Property | Type | Description | | - | - | - | | `frameTop` | `number` | The iframe's top edge relative to the host viewport. | | `height` | `number` | - | | `scrollY` | `number` | Host scroll offset. | | `width` | `number` | Host viewport size. | *** ### FieldState A shopper-supplied value plus the server's verdict on it. #### Type Parameters | Type Parameter | Default type | | - | - | | `T` | `unknown` | #### Properties | Property | Type | | - | - | | `errors` | `string`\[] | | `status` | [`FieldStatus`](#fieldstatus) | | `updatedAt` | `string` \| `null` | | `value` | `T` \| `null` | *** ### FormatMoneyOptions #### Properties | Property | Type | Description | | - | - | - | | `locale?` | `string` | BCP 47 locale for the number formatting — `"sv-SE"` gives `1 299,00 kr`, `"en-US"` gives `SEK 1,299.00`. Defaults to the runtime's own locale, which is the browser's in the one place this is normally called. On a server that is whatever `NODE_ICU` decided, so pass one explicitly if the output is user-visible there. | | `symbol?` | `boolean` | Render the bare number with no currency symbol (`1 299,00`), for a layout that puts the symbol in its own element. | *** ### GaLink The Google Analytics ids a page's `_ga` / `_ga_` cookies carry, for stitching the storefront session to the checkout's. The regexes are the hosted storefront's (`cart.php`), so both surfaces extract the same values from the same cookies. #### Properties | Property | Type | | - | - | | `clientId` | `string` \| `null` | | `sessionId` | `string` \| `null` | *** ### GoogleTagOptions #### Properties | Property | Type | Description | | - | - | - | | `adsConversionId?` | `string` \| `null` | `AW-XXXXXXXXX`. Configured on the same gtag.js as GA4. | | `ga4MeasurementId?` | `string` \| `null` | `G-XXXXXXX`. Loads gtag.js and configures the property. | | `gaLink?` | \| \{ `clientId?`: `string` \| `null`; `sessionId?`: `string` \| `null`; } \| `null` | GA ids to stitch this page to an existing session (rare; the checkout uses it). | | `gtmContainerId?` | `string` \| `null` | `GTM-XXXXXXX`. Loads the container; events go to the dataLayer. | | `loadBeforeConsent?` | `boolean` | Load GTM / gtag.js before the shopper decides, in Consent Mode with everything denied: Google's recommended "advanced" mode, where the tags send cookieless pings and model conversions. Default false: nothing from Google is injected until `analytics` is granted, and the denied `default` then the `update` are still pushed ahead of the script. Turn it on deliberately: a GTM container loaded this way runs ALL of its tags before a decision, gated only by how each tag reads Consent Mode. | | `sendPageView?` | `boolean` | Let gtag.js send its automatic `page_view` on load. Default true. A single-page app that tracks its own navigations sets this false and calls `analytics.trackPageView()` on every route change instead. | *** ### HandoffParamsOptions #### Properties | Property | Type | Description | | - | - | - | | `cookies?` | `string` \| [`CookieList`](#cookielist) \| `null` | The cookies to read the GA ids from: a `Cookie:` header, or the `{ name, value }` list a framework's cookie jar returns. Defaults to `document.cookie` in a browser; pass the request's on a server. | | `linkGa?` | `boolean` | Set false to leave the GA cookies alone. Default true. | | `requireConsent?` | `boolean` | False means the storefront runs without consent and the checkout should track ungated, the way a hosted shop without the consent app does: no `consentCategories` is sent at all. Default true. | *** ### HostedCheckoutReturn What the hosted checkout appends when it sends the shopper back after a completed order: `/success/?hash=…&t=…`. #### Properties | Property | Type | Description | | - | - | - | | `hash` | `string` \| `null` | Legacy integrity hash. Informational — confirm via `confirmation()`. | | `orderNumber` | `number` | - | | `timestamp` | `number` \| `null` | Unix seconds the redirect was issued. | *** ### HostedCheckoutUrlInput #### Properties | Property | Type | Description | | - | - | - | | `language?` | `string` | Preselect the checkout language, flash-free on first paint. | | `sessionId` | `string` | - | | ~~`shopId?`~~ | `string` \| `number` | **Deprecated** Renamed to [storeId](#storeid-3) in 1.0.0-beta.4. Up to beta.3 this defaulted to the key's shop prefix, which the hosted checkout does not recognise; the value must be the shop's numeric id (`Cart.storeId`) and anything else — `shopkit.shopId`/`shopPrefix` included — is rejected with a `ShopkitConfigError`. Read only when `storeId` is absent; removed before 1.0.0. | | `storeId?` | `string` \| `number` | The shop's NUMERIC id — `Cart.storeId` — which is what the hosted checkout's path wants (`/checkout/101928/…`). Not the prefix in the publishable key (`101928Y`, `shopkit.shopPrefix`): the checkout does not recognise that value. Optional because shopkit remembers it from every cart the client receives. When neither is available `hostedUrl()` throws rather than guess. | *** ### ImageSrcSetOptions Resize/encode parameters for Quickbutik's image CDN (imgix-compatible). Every field is optional and omitted params fall back to the CDN's own defaults. In a local/rig environment images are served straight from S3, which ignores these — the URLs stay valid, they just come back full-size. #### Extends * [`ProductImageUrlOptions`](#productimageurloptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `auto?` | `string` \| `null` | Automatic optimisations → `auto`. Defaults to `"format"`, which is what the platform's own storefront sends: it serves WebP/AVIF to browsers that advertise support and the original format to those that do not. Pass `null` to send no `auto` at all. | [`ProductImageUrlOptions`](#productimageurloptions).[`auto`](#auto-2) | | `background?` | `string` | Padding colour for `fit: "fill"` → `bg`. Hex without the `#`. | [`ProductImageUrlOptions`](#productimageurloptions).[`background`](#background-2) | | `baseUrl?` | `string` \| `null` | Base URL for the shop's image storage, used only as a fallback when the API returned no absolute `url` — an older api-core, or a fixture. It must be the shop-scoped base *without* the `products/` segment, e.g. `https://cdn.quickbutik.com/images/`. Set it once as `imageBaseUrl` on the client config rather than per call site. | [`ProductImageUrlOptions`](#productimageurloptions).[`baseUrl`](#baseurl-1) | | `cacheBust?` | `boolean` | Append the image's `contentHash` as a `v` parameter so a replaced file is not served stale from the CDN. On by default; the hash changes only when the binary does, so it costs no cache hits. | [`ProductImageUrlOptions`](#productimageurloptions).[`cacheBust`](#cachebust-1) | | `crop?` | `string` | Crop anchor → `crop`, e.g. `"faces,center"`. Only read when `fit: "crop"`. | [`ProductImageUrlOptions`](#productimageurloptions).[`crop`](#crop-2) | | `densities?` | readonly `number`\[] | Pixel ratios, emitted as `x` descriptors (`2x`). Defaults to `[1, 2]` when a `width` is known and no `widths` were given. | - | | `dpr?` | `number` | Device pixel ratio → `dpr`. Multiplies `w`/`h` CDN-side. For a responsive image prefer `densities` on ``, which emits one candidate per ratio and lets the browser choose. | [`ProductImageUrlOptions`](#productimageurloptions).[`dpr`](#dpr-2) | | `fit?` | `"clip"` \| `"crop"` \| `"fill"` \| `"facearea"` \| `"max"` \| `"min"` \| `"scale"` | How the image fills `width`×`height` → `fit`. The CDN default is `clip`. | [`ProductImageUrlOptions`](#productimageurloptions).[`fit`](#fit-2) | | `format?` | `string` | Output format → `fm`, e.g. `"webp"`, `"avif"`, `"jpg"`, `"png"`. | [`ProductImageUrlOptions`](#productimageurloptions).[`format`](#format-2) | | `height?` | `number` | Rendered height in CSS pixels → `h`. | [`ProductImageUrlOptions`](#productimageurloptions).[`height`](#height-4) | | `quality?` | `number` | JPEG/WebP quality, 1–100 → `q`. | [`ProductImageUrlOptions`](#productimageurloptions).[`quality`](#quality-2) | | `width?` | `number` | Rendered width in CSS pixels → `w`. | [`ProductImageUrlOptions`](#productimageurloptions).[`width`](#width-3) | | `widths?` | readonly `number`\[] | Explicit candidate widths, emitted as `w` descriptors (`600w`) — pair with a `sizes` attribute. Wins over `densities`. | - | *** ### ImageTransform Resize/encode parameters for Quickbutik's image CDN (imgix-compatible). Every field is optional and omitted params fall back to the CDN's own defaults. In a local/rig environment images are served straight from S3, which ignores these — the URLs stay valid, they just come back full-size. #### Extended by * [`ProductImageUrlOptions`](#productimageurloptions) #### Properties | Property | Type | Description | | - | - | - | | `auto?` | `string` \| `null` | Automatic optimisations → `auto`. Defaults to `"format"`, which is what the platform's own storefront sends: it serves WebP/AVIF to browsers that advertise support and the original format to those that do not. Pass `null` to send no `auto` at all. | | `background?` | `string` | Padding colour for `fit: "fill"` → `bg`. Hex without the `#`. | | `crop?` | `string` | Crop anchor → `crop`, e.g. `"faces,center"`. Only read when `fit: "crop"`. | | `dpr?` | `number` | Device pixel ratio → `dpr`. Multiplies `w`/`h` CDN-side. For a responsive image prefer `densities` on ``, which emits one candidate per ratio and lets the browser choose. | | `fit?` | `"clip"` \| `"crop"` \| `"fill"` \| `"facearea"` \| `"max"` \| `"min"` \| `"scale"` | How the image fills `width`×`height` → `fit`. The CDN default is `clip`. | | `format?` | `string` | Output format → `fm`, e.g. `"webp"`, `"avif"`, `"jpg"`, `"png"`. | | `height?` | `number` | Rendered height in CSS pixels → `h`. | | `quality?` | `number` | JPEG/WebP quality, 1–100 → `q`. | | `width?` | `number` | Rendered width in CSS pixels → `w`. | *** ### LegacyHandoff A `legacy` handoff, and what does and does not carry over from `v2`. **The shopper comes back, the same way as from `v2`.** After a completed order the legacy checkout redirects to `/success/?t=…&hash=…` — only the ORIGIN of your `successUrl` is used, exactly as on `v2`, so one thank-you route serves both checkouts — and its back links go to your `backUrl`. [CheckoutResource.parseReturnUrl](#parsereturnurl) reads that return, and the uuid `start()` remembered is what `pollConfirmation()` (and `useOrderConfirmation()` / `` with no id given) confirms the order by. `hash` is computed the same way on both checkouts. The post-purchase-offer token (`&ppo=`) is only appended when `successUrl` is on a host the shop owns, so a headless storefront on its own domain should not expect one. Up to kit 1.3 this said the opposite — the legacy checkout used to redirect to the shop's own platform storefront and could not be pointed anywhere else. The platform now honours the handoff's `successUrl` and `backUrl` on both checkouts. Three things that still differ from `v2`: 1. **`successMode: "inline"` does not apply.** The legacy checkout always redirects, so the platform refuses an inline handoff for a legacy shop with a 400 (`details.reason: "legacy_checkout_unsupported"`) before any order is created. Pass a real `successUrl`. 2. **There is no session.** `getSession()` and patching do not apply. Poll [CheckoutResource.confirmation](#confirmation) with [legacyOrderUuid](#legacyorderuuid) instead — the confirmation endpoint takes either handle. 3. **A failed payment reads as `no_attempt`, not `failed`.** The legacy checkout leaves a failed order looking untouched, so a `timeout` or `no_attempt` outcome is not evidence the shopper gave up. Rely on the merchant's own order confirmation email as the source of truth. Cart-level campaign and säljplats override prices are also NOT carried over: the legacy checkout re-prices every line from the catalog. A shop that sells on campaign pricing needs checkout-v2. Minor, and outside the storefront's control: the order records the IP the platform saw for the caller, which for a headless storefront is a platform address rather than the shopper's. Merchant-visible on the order; it affects nothing about the handoff, the payment or the confirmation. #### Properties | Property | Type | Description | | - | - | - | | `cartId` | `string` | - | | `checkout` | `"legacy"` | - | | `legacyOrderUuid` | `string` \| `null` | The unpaid order this handoff created — or reused, when the shopper has already been here with this cart. Also the handle to poll [CheckoutResource.confirmation](#confirmation) with. Null only in the pathological case of a legacy order carrying no uuid, which is also the only case where `hostedUrl` is null on a configured host. `start()` refuses that response rather than hand back a handoff nothing can confirm. | *** ### ListParams #### Properties | Property | Type | | - | - | | `limit?` | `number` | | `offset?` | `number` | *** ### MetaPixelOptions #### Properties | Property | Type | Description | | - | - | - | | `pixelId` | `string` | The numeric pixel id from the shop's tracking configuration. | *** ### MountCheckoutInput Input to `checkout.start()`: a `CreateSessionInput` whose cart is optional. The `successUrl` rule is the same — required unless `successMode: "inline"`. #### Extends * [`StartCheckoutInput`](#startcheckoutinput).[`EmbedRenderOptions`](#embedrenderoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `backUrl?` | `string` | Where the hosted checkout's "back to shop" / "continue shopping" links point — the header logo and back arrow, the empty-cart screen and the order confirmation. Same URL rule as `successUrl`: any `https` host, `http` only for `localhost`/loopback. When omitted the checkout falls back to the shop's storefront URL, then to the origin of `successUrl` — which for a headless storefront is usually the right page anyway. Set it when your storefront lives on a path or you want a specific landing page. In `inline` success mode it is the ONLY way home from the confirmation, so a headless or campaign storefront should set it to the page the shopper came from. | [`CreateSessionInput`](#createsessioninput).[`backUrl`](#backurl-2) | | `cancelUrl?` | `string` | Where "back to cart" goes. | [`CreateSessionInput`](#createsessioninput).[`cancelUrl`](#cancelurl-2) | | `cartId?` | `string` | Defaults to the remembered cart (created if this visitor has none). | [`StartCheckoutInput`](#startcheckoutinput).[`cartId`](#cartid-6) | | `confirmation?` | `"redirect"` \| `"inline"` | What happens when the order completes. - `"redirect"` (default) — leave the page for the confirmed order, at exactly the URL the redirect checkout would have sent the shopper to (`/success/?hash=…`), so one thank-you page serves both paths. - `"inline"` — stay on the page and let the frame render its own confirmation. | [`EmbedRenderOptions`](#embedrenderoptions).[`confirmation`](#confirmation-3) | | `currency?` | `string` \| `null` | The currency the shopper is browsing in. Defaults to the client's currency (`client.currency`); pass `null` to send none. The shop decides what happens with it, exactly as for product and cart reads: a `"display"` currency leaves the session in the shop's currency and the response carries it as [CheckoutSession.displayCurrency](#displaycurrency); a `"charge"` currency prices and charges the session in it; anything else has no effect. Fixed when the session is created — a session for the same cart in a different currency is a new session. checkout-v2 only. | [`CreateSessionInput`](#createsessioninput).[`currency`](#currency-8) | | `embed?` | [`SessionEmbed`](#sessionembed) | Declare where this session may be framed. Required for an embedded checkout and ignored by the redirect one — see [SessionEmbed](#sessionembed). | [`CreateSessionInput`](#createsessioninput).[`embed`](#embed-2) | | `embedOrigin?` | `string` | The origin recorded on the session as the only one allowed to frame it. Defaults to this page's. Override only when the page creating the session is not the page that will show it. | - | | `fallbackRedirect?` | `boolean` | Navigate to the hosted checkout when there is nothing to frame, and when the frame that was built never answers. On by default — a shopper must never be left looking at an empty box because a shop is configured differently than the page assumed, or because this page is not the origin the session was created for. Turn it off to render your own message from the `fallback` event; its `url` is where the shopper should go. | [`EmbedRenderOptions`](#embedrenderoptions).[`fallbackRedirect`](#fallbackredirect-1) | | `handleNavigation?` | `boolean` | Perform the contract's default navigations (`navigate`, `redirect`, `complete`). Off means the handle only reports; YOU must then perform the redirect break-out yourself or redirect payment methods will not work. Defaults to on. | [`EmbedRenderOptions`](#embedrenderoptions).[`handleNavigation`](#handlenavigation-1) | | `handshakeTimeoutMs?` | `number` | Override the 15s handshake deadline. For tests, chiefly. | [`EmbedRenderOptions`](#embedrenderoptions).[`handshakeTimeoutMs`](#handshaketimeoutms-1) | | `language?` | `string` | Checkout UI language ("sv", "en", "en-US"). Validation is lenient — a code the checkout cannot translate falls back to the shop default rather than failing. | [`CreateSessionInput`](#createsessioninput).[`language`](#language-2) | | `minHeight?` | `number` | Height of the frame before the first `height` message, and the floor it never drops below. Set it to roughly the height of your checkout so the page does not jump on first paint. | [`EmbedRenderOptions`](#embedrenderoptions).[`minHeight`](#minheight-1) | | `prefill?` | [`SessionPrefill`](#sessionprefill) | - | [`CreateSessionInput`](#createsessioninput).[`prefill`](#prefill) | | `returnUrl?` | `string` | Where a redirect payment method returns the shopper. Defaults to this page's URL with the kit's own parameters stripped, so a return does not stack `?qb_checkout_session=` and `qb_checkout_shop=` twice. Must share an origin with `embedOrigin`. | - | | `storefrontId?` | `string` | The campaign storefront this checkout is started from — `sf_…`. Binds the session to the campaign: its prices apply, it must be live, its quantity limits are enforced, and its id goes on the order. Falls back to the client's `storefront` binding; when neither is set the field is not sent, and a cart already bound to a campaign passes its binding on server-side. With an explicit `cartId` any campaign may be named. Without one (`checkout.start()` / `buyNow()` on the remembered cart) it must match the client's binding — see `StorefrontAttribution`. | [`CreateSessionInput`](#createsessioninput).[`storefrontId`](#storefrontid-3) | | `successMode?` | `"redirect"` \| `"inline"` | `"redirect"` (the default when omitted) or `"inline"`. See [SuccessMode](#successmode-7). | [`CreateSessionInput`](#createsessioninput).[`successMode`](#successmode-2) | | `successUrl?` | `string` | Where the shopper lands after paying. Required unless `successMode: "inline"`, where the checkout never redirects. Any `https` URL is accepted — the host needs no registration and no relationship to the shop's platform URL. `http` is accepted only for `localhost` and loopback addresses; a `javascript:` URL, or any other scheme, is rejected with 400. Only the ORIGIN is used for the post-payment redirect: the hosted checkout sends the shopper to `/success/?hash=…&t=…`, so mount a route there (see `parseReturnUrl`). | [`CreateSessionInput`](#createsessioninput).[`successUrl`](#successurl-2) | | `surface?` | `"embed"` \| `"link"` \| `"hosted"` \| `"shopkit"` \| `"agentic"` | Where the campaign was presented to this shopper. Only sent together with a `storefrontId`; defaults to the client's surface, then `"shopkit"`. | [`CreateSessionInput`](#createsessioninput).[`surface`](#surface-3) | | `theme?` | `"light"` \| `"dark"` | Which theme the hosted checkout is painted in for this shopper. Set it when your own pages are dark, so the checkout does not flash white on the way in. Omitting it is not the same as passing `"light"`: omit it and the checkout follows the theme the merchant chose for their shop, pass `"light"` and this checkout stays light whatever the merchant chose. Fixed when the session is created and not changeable afterwards, so decide it with the rest of the page's theme. If you omit it, the merchant's choice applies live — a shopper with the checkout already open sees it change when the merchant changes it. | [`CreateSessionInput`](#createsessioninput).[`theme`](#theme-1) | | `title?` | `string` | The iframe's accessible name. Defaults to `"Checkout"`. | [`EmbedRenderOptions`](#embedrenderoptions).[`title`](#title-2) | *** ### NextLikeMetadata Next.js `Metadata`, structurally. Declared here rather than imported from `next`: shopkit must not depend on a framework, and this is the subset `buildSeo` can fill. Assignable to Next's own `Metadata` type at the call site. #### Properties | Property | Type | | - | - | | `alternates?` | `object` | | `alternates.canonical?` | `string` | | `description?` | `string` | | `openGraph?` | `object` | | `openGraph.description?` | `string` | | `openGraph.images?` | `object`\[] | | `openGraph.locale?` | `string` | | `openGraph.siteName?` | `string` | | `openGraph.title?` | `string` | | `openGraph.type?` | `string` | | `openGraph.url?` | `string` | | `other?` | `Record`\<`string`, `string`> | | `robots?` | `object` | | `robots.follow` | `boolean` | | `robots.index` | `boolean` | | `title?` | `string` | | `twitter?` | `object` | | `twitter.card?` | `"summary"` \| `"summary_large_image"` | | `twitter.creator?` | `string` | | `twitter.description?` | `string` | | `twitter.images?` | `string`\[] | | `twitter.site?` | `string` | | `twitter.title?` | `string` | *** ### OrderLine A line the server added on top of the products (shipping, fee, discount). #### Properties | Property | Type | Description | | | | | | - | - | - | - | - | - | - | | `amount` | `number` | Signed: negative on discounts. | | | | | | `id` | `string` | - | | | | | | `label` | `string` | - | | | | | | `tag` | `string` | `shipping` | `payment` | `promocode` | `free_shipping` | … | | `taxAmount?` | `number` | - | | | | | | `taxRate?` | `number` | - | | | | | *** ### Page Cursor-paginated collection, as the gateway returns it. #### Type Parameters | Type Parameter | | - | | `T` | #### Properties | Property | Type | | - | - | | `data` | `T`\[] | | `has_more` | `boolean` | | `next_cursor` | `string` \| `null` | *** ### ParsedPublishableKey #### Properties | Property | Type | Description | | - | - | - | | `key` | `string` | The whole key, as it must be sent in `Authorization: Bearer …`. | | `shopPrefix` | `string` | The shop's storage prefix (`101928Y`), as encoded in the key. It is the folder the shop's files live under on the CDN — `https://cdn.quickbutik.com/images//products/` — and the value an `imageBaseUrl` is built from. It is NOT the shop's numeric id: the hosted checkout URL wants that one (`/checkout/101928/…`), and it arrives on every cart as `Cart.storeId`. | *** ### PatchResult What a `PATCH /v2/checkout/sessions/:id` answers with — the fields and data after the change, plus what the change invalidated. #### Properties | Property | Type | Description | | - | - | - | | `data` | [`SessionDataMap`](#sessiondatamap) | - | | `fields` | [`SessionFieldMap`](#sessionfieldmap) | - | | `invalidatedFields` | `string`\[] | Fields whose value is now stale because a dependency changed. | | `isComplete` | `boolean` | - | | `resolvedData` | `string`\[] | Data nodes that were re-resolved as a result. | *** ### PickProductImageOptions #### Properties | Property | Type | Description | | - | - | - | | `imageId?` | `number` | Pick by image id instead of by position. Wins over `index`. | | `includePending?` | `boolean` | Include images whose binary is still being processed. Off by default: a pending image's URL 404s until the ingest job finishes. | | `index?` | `number` | Position in display order. Defaults to 0 — the main image. | *** ### PollConfirmationOptions #### Properties | Property | Type | Description | | - | - | - | | `maxPolls?` | `number` | Hard cap on polls. Default 20. | | `maxTotalMs?` | `number` | Hard cap on total wall time in ms. Default 90000. | | `onUpdate?` | (`confirmation`) => `void` | Called after every poll, for a live "creating your order…" UI. | | `signal?` | `AbortSignal` | - | *** ### Product A product as the storefront sees it — visible products only, no cost prices, no supplier data. Served by api-core's storefront controller, which is the only products surface a publishable key can reach. #### Properties | Property | Type | Description | | - | - | - | | `currency?` | `string` | The currency every price on this product is in — the client's chosen currency when the shop offers it, else the shop's own. Format with this, never a hardcoded code. Absent from a platform older than the field. | | `description` | `string` \| `null` | - | | `id` | `string` | Prefixed id (`prod_123`). Pass it straight back to `cart.addItem` — the gateway strips the prefix on the way to api-core. | | `images` | [`ProductImage`](#productimage)\[] | - | | `name` | `string` \| `null` | - | | `options?` | [`ProductOptionType`](#productoptiontype)\[] | - | | `price` | `number` \| `null` | Display price of the product, in minor units. | | `relatedProducts?` | [`RelatedProducts`](#relatedproducts-1) | The product's related products. Served **only** by a single-product read (`products.get`); absent on `products.list` and search results. | | `sections?` | [`ProductSection`](#productsection)\[] | Merchant-authored content sections, in the merchant's order. Empty when the product has none; absent from responses of API deployments that predate the field. | | `seoDescription` | `string` \| `null` | - | | `seoTitle` | `string` \| `null` | - | | `slug` | `string` \| `null` | - | | `taxRate` | `number` \| `null` | VAT percentage (25, 12, 6 …). | | `variants` | [`ProductVariant`](#productvariant)\[] | - | | `visible` | `boolean` \| `null` | - | *** ### ProductControllerOptions #### Properties | Property | Type | Description | | - | - | - | | `initialVariantId?` | `number` | Preselect this variant — a deep link, or a "recently viewed" restore. | | `selectFirstAvailable?` | `boolean` | Preselect the first purchasable variant instead of starting empty. Off by default, for the same reason React's `ProductProvider` defaults it off: an empty start shows a price RANGE, which is honest for a product whose variants differ in price, and it does not put words in the shopper's mouth about which colour they wanted. | *** ### ProductImage #### Properties | Property | Type | Description | | - | - | - | | `altText` | `string` \| `null` | - | | `contentHash` | `string` \| `null` | Hash of the binary, appended as a cache-buster by `resolveProductImageUrl`. The literal `"temp"` marks an image whose file is still being processed. | | `date` | `string` \| `null` | - | | `id` | `number` | - | | `path` | `string` \| `null` | The bare storage filename (`5c7b0e7e1802c.jpeg`). **Not** a URL: it is missing the shop's storage prefix, which no storefront credential can see, so `

` resolves against your own origin and 404s. Use `url` instead. Kept because the field is part of the existing contract and identifies the file. | | `position` | `number` \| `null` | - | | `productId` | `number` | - | | `url` | `string` \| `null` | Absolute URL of the image file, with **no** resize parameters — the only renderable value here. Add the pixels yourself (`?w=&h=`, imgix-compatible) or let `resolveProductImageUrl` / `` do it. Null when the image has no file yet. | *** ### ProductImageUrlOptions Resize/encode parameters for Quickbutik's image CDN (imgix-compatible). Every field is optional and omitted params fall back to the CDN's own defaults. In a local/rig environment images are served straight from S3, which ignores these — the URLs stay valid, they just come back full-size. #### Extends * [`ImageTransform`](#imagetransform) #### Extended by * [`ImageSrcSetOptions`](#imagesrcsetoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `auto?` | `string` \| `null` | Automatic optimisations → `auto`. Defaults to `"format"`, which is what the platform's own storefront sends: it serves WebP/AVIF to browsers that advertise support and the original format to those that do not. Pass `null` to send no `auto` at all. | [`ImageTransform`](#imagetransform).[`auto`](#auto-1) | | `background?` | `string` | Padding colour for `fit: "fill"` → `bg`. Hex without the `#`. | [`ImageTransform`](#imagetransform).[`background`](#background-1) | | `baseUrl?` | `string` \| `null` | Base URL for the shop's image storage, used only as a fallback when the API returned no absolute `url` — an older api-core, or a fixture. It must be the shop-scoped base *without* the `products/` segment, e.g. `https://cdn.quickbutik.com/images/`. Set it once as `imageBaseUrl` on the client config rather than per call site. | - | | `cacheBust?` | `boolean` | Append the image's `contentHash` as a `v` parameter so a replaced file is not served stale from the CDN. On by default; the hash changes only when the binary does, so it costs no cache hits. | - | | `crop?` | `string` | Crop anchor → `crop`, e.g. `"faces,center"`. Only read when `fit: "crop"`. | [`ImageTransform`](#imagetransform).[`crop`](#crop-1) | | `dpr?` | `number` | Device pixel ratio → `dpr`. Multiplies `w`/`h` CDN-side. For a responsive image prefer `densities` on ``, which emits one candidate per ratio and lets the browser choose. | [`ImageTransform`](#imagetransform).[`dpr`](#dpr-1) | | `fit?` | `"clip"` \| `"crop"` \| `"fill"` \| `"facearea"` \| `"max"` \| `"min"` \| `"scale"` | How the image fills `width`×`height` → `fit`. The CDN default is `clip`. | [`ImageTransform`](#imagetransform).[`fit`](#fit-1) | | `format?` | `string` | Output format → `fm`, e.g. `"webp"`, `"avif"`, `"jpg"`, `"png"`. | [`ImageTransform`](#imagetransform).[`format`](#format-1) | | `height?` | `number` | Rendered height in CSS pixels → `h`. | [`ImageTransform`](#imagetransform).[`height`](#height-3) | | `quality?` | `number` | JPEG/WebP quality, 1–100 → `q`. | [`ImageTransform`](#imagetransform).[`quality`](#quality-1) | | `width?` | `number` | Rendered width in CSS pixels → `w`. | [`ImageTransform`](#imagetransform).[`width`](#width-2) | *** ### ProductJsonLdOptions #### Properties | Property | Type | | - | - | | `brand?` | `string` | | `currency?` | `string` | | `images?` | `string`\[] | | `url?` | `string` | *** ### ProductListParams Which campaign storefront prices a product read. A client bound to a campaign (`ShopkitConfig.storefront` / `storefrontId`) sends its id on every product read, so the catalog it shows carries the same campaign prices its cart will charge — a product page that says 199 kr above a cart that says 149 kr is the bug this closes. Pass one here to price a single read for a different campaign; reads are stateless, so any campaign may be named. `null` opts a bound client out for this call and reads the shop's ordinary prices. #### Extends * [`RequestOptions`](#requestoptions).[`ProductReadOptions`](#productreadoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `currency?` | `string` \| `null` | The currency to price this read in. Defaults to the client's (`client.currency`); `null` reads the shop's own prices. The response's `product.currency` says what the prices actually came back in. | [`ProductReadOptions`](#productreadoptions).[`currency`](#currency-14) | | `cursor?` | `string` | Opaque cursor from a previous page's `next_cursor`. | - | | `limit?` | `number` | Page size, 1–200. Defaults to the gateway's 50 when omitted. | - | | `signal?` | `AbortSignal` | Abort the underlying fetch (component unmount, route change). | [`RequestOptions`](#requestoptions).[`signal`](#signal-3) | | `storefrontId?` | `string` \| `null` | The campaign storefront (`sf_…`) to price this read for. Defaults to the client's binding; `null` means none. A malformed id throws a `ShopkitConfigError` before the request goes out. | [`ProductReadOptions`](#productreadoptions).[`storefrontId`](#storefrontid-6) | *** ### ProductOptionType A selectable option ("Size"), owned by the product. #### Properties | Property | Type | | - | - | | `id` | `number` | | `name` | `string` \| `null` | | `position` | `number` \| `null` | *** ### ProductOptionValue One concrete choice of an option ("XL"), referenced by a variant. #### Properties | Property | Type | | - | - | | `id` | `number` | | `name` | `string` \| `null` | | `optionId` | `number` \| `null` | | `position` | `number` \| `null` | *** ### ProductReadOptions Which campaign storefront prices a product read. A client bound to a campaign (`ShopkitConfig.storefront` / `storefrontId`) sends its id on every product read, so the catalog it shows carries the same campaign prices its cart will charge — a product page that says 199 kr above a cart that says 149 kr is the bug this closes. Pass one here to price a single read for a different campaign; reads are stateless, so any campaign may be named. `null` opts a bound client out for this call and reads the shop's ordinary prices. #### Extended by * [`ProductListParams`](#productlistparams) * [`ProductSearchParams`](#productsearchparams) #### Properties | Property | Type | Description | | - | - | - | | `currency?` | `string` \| `null` | The currency to price this read in. Defaults to the client's (`client.currency`); `null` reads the shop's own prices. The response's `product.currency` says what the prices actually came back in. | | `storefrontId?` | `string` \| `null` | The campaign storefront (`sf_…`) to price this read for. Defaults to the client's binding; `null` means none. A malformed id throws a `ShopkitConfigError` before the request goes out. | *** ### ProductSearchParams Which campaign storefront prices a product read. A client bound to a campaign (`ShopkitConfig.storefront` / `storefrontId`) sends its id on every product read, so the catalog it shows carries the same campaign prices its cart will charge — a product page that says 199 kr above a cart that says 149 kr is the bug this closes. Pass one here to price a single read for a different campaign; reads are stateless, so any campaign may be named. `null` opts a bound client out for this call and reads the shop's ordinary prices. #### Extends * [`RequestOptions`](#requestoptions).[`ProductReadOptions`](#productreadoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `categoryId?` | `string` \| `number` | Restrict to one category — `"cat_12"` or `12`, both accepted (a bare number is prefixed for you, because the gateway rejects it otherwise). Direct membership only — child categories are not walked, so filtering by a parent returns nothing that lives solely in its children. Read the ids from [CategoriesResource.list](#list), which the same scope reaches. | - | | `currency?` | `string` \| `null` | The currency to price this read in. Defaults to the client's (`client.currency`); `null` reads the shop's own prices. The response's `product.currency` says what the prices actually came back in. | [`ProductReadOptions`](#productreadoptions).[`currency`](#currency-14) | | `cursor?` | `string` | Opaque cursor from a previous page's `next_cursor`. | - | | `limit?` | `number` | Page size, 1–200. Defaults to the gateway's 50 when omitted. | - | | `maxPrice?` | `number` | - | - | | `minPrice?` | `number` | Inclusive price bounds in **minor units** — `20000` is 200,00 kr. **Always in the shop's own currency**, whatever currency the read is priced in: filtering and `sortBy: "price"` run on the stored prices. **These match the undiscounted list price.** Storefront discounts are applied per page after the query runs, so on a shop running a discount a product can come back priced outside the bounds you asked for. The same caveat applies to `sortBy: "price"`. An **inverted range** (`minPrice` above `maxPrice`) is rejected with a 400 rather than silently returning nothing. Order them, or swap them before calling. | - | | `search?` | `string` | Free-text term, matched against product name, SKU and GTIN, and against variant SKU/GTIN and variant option values. Whitespace-separated words are AND-ed and order-independent, so "merino crew" matches a "Crew neck, merino" product. Only the first 10 words are considered. | - | | `signal?` | `AbortSignal` | Abort the underlying fetch (component unmount, route change). | [`RequestOptions`](#requestoptions).[`signal`](#signal-3) | | `sortBy?` | [`ProductSortField`](#productsortfield) | Defaults to `createdAt` server-side. | - | | `sortOrder?` | `"desc"` \| `"asc"` | Defaults to `desc` server-side. | - | | `storefrontId?` | `string` \| `null` | The campaign storefront (`sf_…`) to price this read for. Defaults to the client's binding; `null` means none. A malformed id throws a `ShopkitConfigError` before the request goes out. | [`ProductReadOptions`](#productreadoptions).[`storefrontId`](#storefrontid-6) | *** ### ProductSection A merchant-authored content section of a product page ("Size guide", "Care", "Delivery"), in the order the merchant arranged them. Rendered server-side exactly as the Quickbutik theme renders it: a section linked to a shared template already carries the template's text, and the `[STOCKLEFT]`, `[PRICE]` and `[BEFOREPRICE]` merge tags are replaced. #### Properties | Property | Type | Description | | - | - | - | | `content` | `string` | Merchant-authored **HTML**. May be empty when the section has a title only. Sanitize it before injecting it as HTML. | | `id` | `string` | Stable across edits and unique within the product — a render key. | | `title` | `string` | Heading. May be empty when the section has content only. | *** ### ProductSnapshot Everything derived from one product plus the shopper's current choices. The read half of [ProductController](#productcontroller), and the exact shape React's `ProductState` is built from — the two must not drift, so the hook spreads this rather than restating it. #### Properties | Property | Type | Description | | - | - | - | | `hasOptions` | `boolean` | False for a simple product — render no picker. | | `isComplete` | `boolean` | True once every option group has a choice (always true with no options). | | `options` | [`VariantOptionGroupState`](#variantoptiongroupstate)\[] | Option groups with per-value `selected` / `available` flags, in display order. | | `price` | [`VariantPriceState`](#variantpricestate) | Price for the current selection: exact figure, or a range before that. | | `product` | [`Product`](#product-1) | - | | `selectedVariant` | [`ProductVariant`](#productvariant) \| `null` | The variant the selection identifies, or null while it is incomplete. | | `selection` | [`VariantSelection`](#variantselection) | The raw selection, keyed by option id. Partial until every group is chosen. | *** ### ProductVariant #### Properties | Property | Type | Description | | - | - | - | | `barcode` | `string` \| `null` | - | | `hidden` | `boolean` \| `null` | - | | `id` | `number` | Numeric — this is the id the Cart API takes as `variantId`. | | `imageId?` | `number` \| `null` | The variant's own image: the `id` of one of the product's `images`, so `product.images.find((image) => image.id === variant.imageId)` resolves it — swap the gallery to it when the shopper picks this variant. Null when the variant has no image of its own (show the product's gallery), and always on the single synthetic variant of a simple product. Never points at an image that is not in `images`. Absent from responses of API deployments that predate the field. | | `maxPurchaseQty` | `number` \| `null` | - | | `minPurchaseQty` | `number` \| `null` | - | | `options` | [`ProductOptionValue`](#productoptionvalue)\[] | - | | `price` | [`ProductVariantPrice`](#productvariantprice-1) | - | | `sku` | `string` | - | | `stock` | [`ProductVariantStock`](#productvariantstock-1) | - | | `weight` | `number` \| `null` | Grams. | *** ### ProductVariantPrice #### Properties | Property | Type | Description | | - | - | - | | `comparePrice` | `number` \| `null` | "Before" price, for a struck-through comparison. Null when not on sale. | | `price` | `number` \| `null` | - | *** ### ProductVariantStock #### Properties | Property | Type | | - | - | | `preorder` | `boolean` \| `null` | | `stock` | `number` \| `null` | *** ### PurchaseEvent The order a thank-you page reports, in major units. #### Properties | Property | Type | Description | | - | - | - | | `affiliation?` | `string` | GA4 `affiliation` — the store the order was placed with. | | `currency` | `string` | - | | `items` | [`CommerceItem`](#commerceitem)\[] | - | | `shipping?` | `number` | - | | `tax?` | `number` | - | | `transaction_id` | `string` | The order number. | | `value` | `number` | - | *** ### RelatedProducts #### Properties | Property | Type | Description | | - | - | - | | `mode` | [`RelatedProductsMode`](#relatedproductsmode-1) | - | | `products` | [`RelatedProductSummary`](#relatedproductsummary)\[] | Visible related products, never the product itself. `specific`: at most 12, in the merchant's order. `category`: at most 8, newest first, without sold-out products when the shop hides them. Always empty for `none`. | *** ### RelatedProductSummary A related product, reduced to what a product card needs. #### Properties | Property | Type | Description | | - | - | - | | `id` | `string` | Prefixed id (`prod_123`) — pass it to `products.get` or `cart.addItem`. | | `image` | [`ProductImage`](#productimage) \| `null` | The product's first image, or null when it has none. | | `name` | `string` \| `null` | - | | `price` | [`ProductVariantPrice`](#productvariantprice-1) | The product's own price, priced like the product list (automatic discounts and `storefrontId` campaign prices included). | | `slug` | `string` \| `null` | - | *** ### RequestOptions #### Extended by * [`ProductListParams`](#productlistparams) * [`ProductSearchParams`](#productsearchparams) #### Properties | Property | Type | Description | | - | - | - | | `signal?` | `AbortSignal` | Abort the underlying fetch (component unmount, route change). | *** ### ResolvedShopkitConfig Config with every default applied and the key already parsed. #### Properties | Property | Type | Description | | - | - | - | | `apiUrl` | `string` | - | | `cartTtlSeconds` | `number` | - | | `checkoutUrl` | `string` | - | | `checkoutUrlConfigured` | `boolean` | Whether `checkoutUrl` was set by the caller rather than defaulted. Decides whether a locally built checkout-v2 URL beats the platform's — see [ShopkitConfig.checkoutUrl](#checkouturl-2). | | `cookieAttributes` | [`CookieAttributes`](#cookieattributes) | - | | `cookies?` | [`CookieAccessor`](#cookieaccessor) | - | | `currency` | `string` \| `null` | The configured default currency, upper-cased; null for the shop's own. | | `fetch` | (`input`, `init?`) => `Promise`\<`Response`> | - | | `headers` | `Record`\<`string`, `string`> | - | | `imageBaseUrl` | `string` \| `null` | - | | `maxRetries` | `number` | - | | `onUnauthorized?` | () => `string` \| `Promise`\<`string` \| `null`> \| `null` | - | | `publishableKey` | `string` | - | | `scopes` | readonly `string`\[] \| `null` \| `undefined` | `null` = pre-flight checking disabled; `undefined` = use the default set. | | `shopPrefix` | `string` | The shop's storage prefix, decoded from the key. Used in CDN image paths; NOT the numeric id the hosted checkout URL needs (that is `Cart.storeId`). | | `storage?` | [`StoragePreference`](#storagepreference) | - | | `storageKeyPrefix` | `string` | - | | `storefront` | [`StorefrontBinding`](#storefrontbinding) \| `null` | The campaign storefront this client sells into, surface defaulted; null when none. | | `timeoutMs` | `number` | - | *** ### ResumeCheckoutInput Presentation and default-behaviour options, shared by `mount` and `resume`. #### Extends * [`EmbedRenderOptions`](#embedrenderoptions) #### Properties | Property | Type | Description | Inherited from | | - | - | - | - | | `confirmation?` | `"redirect"` \| `"inline"` | What happens when the order completes. - `"redirect"` (default) — leave the page for the confirmed order, at exactly the URL the redirect checkout would have sent the shopper to (`/success/?hash=…`), so one thank-you page serves both paths. - `"inline"` — stay on the page and let the frame render its own confirmation. | [`EmbedRenderOptions`](#embedrenderoptions).[`confirmation`](#confirmation-3) | | `fallbackRedirect?` | `boolean` | Navigate to the hosted checkout when there is nothing to frame, and when the frame that was built never answers. On by default — a shopper must never be left looking at an empty box because a shop is configured differently than the page assumed, or because this page is not the origin the session was created for. Turn it off to render your own message from the `fallback` event; its `url` is where the shopper should go. | [`EmbedRenderOptions`](#embedrenderoptions).[`fallbackRedirect`](#fallbackredirect-1) | | `handleNavigation?` | `boolean` | Perform the contract's default navigations (`navigate`, `redirect`, `complete`). Off means the handle only reports; YOU must then perform the redirect break-out yourself or redirect payment methods will not work. Defaults to on. | [`EmbedRenderOptions`](#embedrenderoptions).[`handleNavigation`](#handlenavigation-1) | | `handshakeTimeoutMs?` | `number` | Override the 15s handshake deadline. For tests, chiefly. | [`EmbedRenderOptions`](#embedrenderoptions).[`handshakeTimeoutMs`](#handshaketimeoutms-1) | | `language?` | `string` | - | - | | `minHeight?` | `number` | Height of the frame before the first `height` message, and the floor it never drops below. Set it to roughly the height of your checkout so the page does not jump on first paint. | [`EmbedRenderOptions`](#embedrenderoptions).[`minHeight`](#minheight-1) | | `storeId?` | `string` \| `number` \| `null` | The shop's numeric id. The return leg carries it as `qb_checkout_shop` next to the session id (`readReturnedCheckout().storeId`); pass it and resume needs no storage at all. When omitted the id remembered with the checkout session, or off the last cart, is used. | - | | `successUrl?` | `string` | Where a completed order lands, as on [MountCheckoutInput](#mountcheckoutinput). | - | | `title?` | `string` | The iframe's accessible name. Defaults to `"Checkout"`. | [`EmbedRenderOptions`](#embedrenderoptions).[`title`](#title-2) | *** ### ReturnedCheckout What the checkout's return route put on this page's URL. #### Properties | Property | Type | Description | | - | - | - | | `sessionId` | `string` | The session to resume. | | `storeId` | `string` \| `null` | The shop's numeric id, or null when the URL did not carry a usable one — a checkout older than the parameter, or a value that is not a number. Pass it to `checkout.resume()` as `storeId`; with null, resume falls back to the id remembered in storage. | *** ### ScopeGuard #### Properties | Property | Modifier | Type | Description | | - | - | - | - | | `declared` | `readonly` | readonly `string`\[] | The scopes this client was told it has. | | `enforced` | `readonly` | `boolean` | Whether local pre-flight checking is on at all. | #### Methods ##### assert() ```ts theme={null} assert(scope, operation): void; ``` Throws [ShopkitScopeError](#shopkitscopeerror) when `scope` is not covered. ###### Parameters | Parameter | Type | | - | - | | `scope` | \| `"products:read"` \| `"cart:read"` \| `"cart:write"` \| `"checkout:read"` \| `"checkout:write"` \| `"storefront:read"` | | `operation` | `string` | ###### Returns `void` ##### has() ```ts theme={null} has(scope): boolean; ``` ###### Parameters | Parameter | Type | | - | - | | `scope` | \| `"products:read"` \| `"cart:read"` \| `"cart:write"` \| `"checkout:read"` \| `"checkout:write"` \| `"storefront:read"` | ###### Returns `boolean` *** ### SeoBreadcrumb #### Properties | Property | Type | Description | | - | - | - | | `name` | `string` | - | | `url?` | `string` | Absolute URL, or a path resolved against `baseUrl`. | *** ### SeoDefaults Site-wide values every page shares. Supply once (via `SeoProvider` or as an argument) so a page only has to name what is specific to it. #### Extended by * [`SeoProps`](/kit/api/react#seoprops) * [`SeoProviderProps`](/kit/api/react#seoproviderprops) #### Properties | Property | Type | Description | | - | - | - | | `baseUrl?` | `string` | Absolute origin of the storefront, e.g. `https://myshop.com`. Required for canonical URLs and for turning a relative image path into an absolute one — crawlers reject relative values in both places. | | `categoryPath?` | `string` | The same for a category — `"/categories/{slug}"`. | | `currency?` | `string` | ISO 4217 code for prices in structured data. A product's own `product.currency` wins; this covers a product from a platform older than that field. With neither, no price is emitted. | | `defaultImage?` | `string` \| [`SeoImage`](#seoimage) | Fallback image for pages with none of their own. | | `locale?` | `string` | BCP 47 locale for OpenGraph (`sv_SE`). Derived from the shop when absent. | | `organization?` | `boolean` | Emit `Organization` structured data alongside the page's own. | | `productPath?` | `string` | Where a product lives, as a template — `"/products/{slug}"`. Lets `` build its own canonical from the product in context, so a page inside `` needs no props at all. `{slug}` and `{id}` are substituted; a product with no slug falls back to `{id}`. A template rather than a function because these defaults cross a client boundary and get compared by value — a function would neither serialize nor memoize. | | `shop?` | [`Shop`](#shop-2) \| `null` | The shop, for site name, logo, locale and Organization structured data. | | `siteName?` | `string` | Shown after the page title. Defaults to the shop's name when a shop is given. | | `titleTemplate?` | `string` | How to compose the final title. `%s` is the page title. Defaults to `"%s · {siteName}"`, and to the bare title with no site name. | | `twitterCreator?` | `string` | - | | `twitterSite?` | `string` | `@handle` of the site, for Twitter cards. | *** ### SeoImage One image, as OpenGraph and schema.org want it. #### Properties | Property | Type | | - | - | | `alt?` | `string` | | `height?` | `number` | | `url` | `string` | | `width?` | `number` | *** ### SeoInput What the page is about. Exactly one of these shapes is used. #### Extended by * [`SeoProps`](/kit/api/react#seoprops) #### Properties | Property | Type | Description | | - | - | - | | `breadcrumbs?` | [`SeoBreadcrumb`](#seobreadcrumb)\[] | Trail for BreadcrumbList when the page builds its own. | | `category?` | [`Category`](#category) \| `null` | A category page — emits BreadcrumbList structured data. | | `description?` | `string` | - | | `images?` | (`string` \| [`SeoImage`](#seoimage))\[] | - | | `jsonLd?` | `Record`\<`string`, `unknown`>\[] | Extra structured data to emit as-is. | | `meta?` | `object`\[] | - | | `noFollow?` | `boolean` | - | | `noIndex?` | `boolean` | Keep the page out of the index — a search results or filter page. | | `product?` | [`Product`](#product-1) \| `null` | A product page — emits Product structured data with offers. | | `title?` | `string` | Overrides whatever the product/category/shop would have produced. | | `url?` | `string` | Absolute URL, or a path resolved against `baseUrl`. | *** ### SeoOpenGraph #### Properties | Property | Type | Description | | - | - | - | | `availability?` | [`SchemaAvailability`](#schemaavailability) | - | | `description?` | `string` | - | | `images` | [`SeoImage`](#seoimage)\[] | - | | `locale?` | `string` | - | | `price?` | `object` | Present only on `type: "product"`, and only when a currency is known. | | `price.amount` | `string` | - | | `price.currency` | `string` | - | | `siteName?` | `string` | - | | `title` | `string` | - | | `type` | `"article"` \| `"website"` \| `"product"` | `website` for the shop and category pages, `product` for a product. | | `url?` | `string` | - | *** ### SeoRobots #### Properties | Property | Type | | - | - | | `follow` | `boolean` | | `index` | `boolean` | *** ### SeoTags Everything a page needs in ``, as data. Deliberately a plain object rather than markup: Next's App Router wants a `Metadata` export, Astro wants tags in its own layout, and a React 19 app can render them anywhere. One builder, three consumers. #### Properties | Property | Type | Description | | - | - | - | | `canonical?` | `string` | Absolute canonical URL. Omitted when no `url`/`baseUrl` was available. | | `description?` | `string` | - | | `jsonLd` | `Record`\<`string`, `unknown`>\[] | schema.org objects for `` from closing the tag and turning shop content into executable markup. A JSON parser reads the escape identically, so nothing is lost by being paranoid here. #### Parameters | Parameter | Type | | - | - | | `node` | `unknown` | #### Returns `string` *** ### storefrontRefusal() ```ts theme={null} function storefrontRefusal(error): StorefrontRefusal | null; ``` Narrow any thrown value to a campaign storefront refusal, or `null` when it is something else — a network error, a 404, an ordinary 409 (an out-of-stock line, say). ```ts theme={null} try { await shopkit.checkout.start({ successUrl }) } catch (error) { const refusal = storefrontRefusal(error) if (refusal?.reason === "storefront_not_live") showCampaignClosed(refusal.effectiveState) else if (refusal?.reason === "storefront_quantity_limit") showLimit(refusal) else throw error } ``` Matches on `details.reason`, not on the HTTP status, so the decoder does not have to know which status each reason travels on. #### Parameters | Parameter | Type | | - | - | | `error` | `unknown` | #### Returns [`StorefrontRefusal`](#storefrontrefusal) | `null` *** ### stripReturnedSessionId() ```ts theme={null} function stripReturnedSessionId(): void; ``` Take the kit's two parameters off the URL, leaving every other parameter and the hash where they were. Stripped at all because the session it names is spent the moment it is resumed: a shopper who reloads would otherwise re-mount a checkout for an order they have already paid for. Stripped only once the resumed frame has said `ready` — not on the pass that starts the resume — because a resume can fail before the frame ever answers: a document the browser refused, a store id nobody could supply, a handshake that timed out into the hosted checkout. With the parameters gone, a reload of that page would find no return leg and take the `mount()` branch; with them still there, the reload resumes again. The platform hands the same cart the same session back either way, so neither path can produce a second order — this is about a reload landing the shopper back in the checkout they paid in, not on a fresh one. `replaceState`, not `pushState` — the parameters were never a place in anyone's history. A no-op when neither is present, so it is safe on every `ready` a frame sends, reloads included. #### Returns `void` *** ### toMajorUnits() ```ts theme={null} function toMajorUnits(amount, currency?): number; ``` Minor units → a number in major units (`9900` SEK → `99`, `990` JPY → `990`). What GA4, Meta and every other analytics vendor want `value` and `price` in. Rounded to the currency's own decimals so the float that comes out is the shortest exact representation (`12.34`, never `12.340000000000002`). Without a currency two decimals are assumed, which is right for every currency the platform sells in by default. #### Parameters | Parameter | Type | | - | - | | `amount` | `number` | | `currency?` | `string` \| `null` | #### Returns `number` *** ### toNextMetadata() ```ts theme={null} function toNextMetadata(tags): NextLikeMetadata; ``` Adapt [SeoTags](#seotags) for a Next.js App Router `generateMetadata` export. ```ts theme={null} export async function generateMetadata({ params }) { const product = await getProduct((await params).slug) return toNextMetadata(buildSeo({ product, ...defaults })) } ``` **Structured data does not come along.** Next's `Metadata` has no slot for a `