Quickbutik Kit

@quickbutik/kit is Quickbutik’s bring-your-own-frontend SDK. With it you can build the storefront in whatever you like: Next.js, Astro, Vue, Svelte, a plain HTML page, or a page in a site builder. Quickbutik is the commerce engine behind it: products, stock, the cart, the hosted checkout, orders, receipts, VAT and bookkeeping. Everything runs on a single publishable key (qb_pk_…) that is safe to ship to a browser. The package is MIT-licensed and on public npm, has no runtime dependencies, and runs the same way on a server and in a browser.

import { createShopkitClient } from "@quickbutik/kit"

const shopkit = createShopkitClient({
  publishableKey: process.env.NEXT_PUBLIC_QUICKBUTIK_PUBLISHABLE_KEY!,
})

const { data: products } = await shopkit.products.list({ limit: 12 })
await shopkit.cart.add({ productId: products[0].id })
const { url } = await shopkit.checkout.start({
  successUrl: "https://myshop.com/success",
  backUrl: "https://myshop.com/",
})
location.assign(url) // the shopper pays in the hosted checkout, then comes back to /success/<orderNumber>

How a sale works

your storefront (publishable key)                hosted Quickbutik checkout              your storefront
catalog → cart → checkout.start()  ──────────►   address · shipping · payment   ──────►  /success/<orderNumber>
                                                 Swish · Klarna · Vipps MobilePay        poll the confirmation
                                                 iDEAL · Apple Pay · Google Pay · cards

Your storefront owns everything before and after the payment: the catalog, product pages, the cart, the checkout button and the thank-you page. The hosted checkout owns payment, shipping choice, discount codes and receipts. You never render a payment form and never handle card data. The same hosted checkout can also run inline on your own page, in a frame the kit creates and drives. See Embedded checkout. The full-page redirect stays the default and the fallback.

What the kit is, and what it is not

It is

The catalog (products, search, variants, categories, shop branding), a server-owned cart, the checkout handoff and order confirmation for the thank-you page. It also remembers the small bits of state every storefront needs (the cart id, the checkout session and the shopper’s currency), handles cookie consent and the shop’s analytics, and prices everything in the shopper’s currency when the shop offers more than one.

It is not

A payment integration (the hosted checkout owns the payment providers, PCI scope, 3-D Secure and wallets), a data-fetching library, or a UI kit. The React and web components render no markup of their own, so you own all of the DOM and all of the styling.

The few deliberate markup exceptions are <ProductImage /> / <qb-product-image> (one <img>), the embedded checkout’s <iframe>, <qb-currency-select>’s <select> when you give it no markup, and the default cookie consent banner, which renders only when you don’t provide your own.

Two keys, two channels

Keeping these two apart is the most important rule when building on Quickbutik.

Channel	Key	Host	Where it may live
Sell: the storefront your visitors use	Publishable key `qb_pk_…`	`https://commerce.quickbutik.com/v2`	Client code, public env vars. Safe to expose
Manage: products, orders, customers	Personal access token `qb_pat_…`	`https://api.quickbutik.com/v2`	Server code and a gitignored `.env` only. Never in a browser

The publishable key reads the visible catalog, runs carts and opens the hosted checkout. It can’t read orders, change products or take payment. The kit refuses a qb_pat_ key outright, so it can’t end up in a browser bundle by accident. Read more in Publishable keys.

Entry points

The kit has four entry points over one framework-free core, plus a script-tag build:

Import	Contains	Runs on
`@quickbutik/kit`	Client, types, storage helpers, SEO builder, variant matrix, image and money helpers. Everything except React and the elements	Server and browser
`@quickbutik/kit/sdk`	Just the client and its types	Server and browser
`@quickbutik/kit/react`	Hooks and headless components (`"use client"`)	Browser, below a client boundary
`@quickbutik/kit/elements`	Headless custom elements (`<qb-product>`, `<qb-cart>`, …)	Browser only
`quickbutik-kit.global.js`	All of the above as `window.Quickbutik`, with the elements pre-registered	Browser only, no build step

Pick your flavour

Pick one flavour for each page, based on your stack. Don’t mix the React layer and the elements on the same page, because you’d end up with two cart stores.

Script tag

Plain HTML, Webflow, WordPress or a CMS theme. You add one <script> tag plus markup, and write no JavaScript of your own.

Web components

Vue, Svelte, Astro, Nuxt or a Vite project without React. @quickbutik/kit/elements.

React

React, Next.js, Remix, TanStack Start. Provider, hooks and headless components from @quickbutik/kit/react.

Vanilla JS

Your own rendering, or a server (Node, Hono, Workers, Astro endpoints). The client from @quickbutik/kit.

Building with an AI agent

If you build with an AI coding agent (Claude Code, Cursor, Lovable, v0, Replit and others), point it at quickbutik.com/agents.md. It is the agent-facing source of truth for building on Quickbutik. It covers creating a shop, the storefront kit, the Storefront and Merchant APIs, and going live. Add two lines like these to the project’s AGENTS.md or CLAUDE.md:

Before any work on the shop, products, cart or checkout: fetch https://quickbutik.com/agents.md
and follow it. Do not rely on memory.

Next steps

Quickstart

A catalog, a cart and a checkout in five minutes.

Checkout flow

The handoff, the successUrl rules and the thank-you page.

Getting Started

Vanilla JavaScript

React

Web Components

Concepts

API Reference

How a sale works

What the kit is, and what it is not

It is

It is not

Two keys, two channels

Entry points

Pick your flavour

Script tag

Web components

React

Vanilla JS

Building with an AI agent

Next steps

Quickstart

Checkout flow

​How a sale works

​What the kit is, and what it is not

It is

It is not

​Two keys, two channels

​Entry points

​Pick your flavour

Script tag

Web components

React

Vanilla JS

​Building with an AI agent

​Next steps

Quickstart

Checkout flow

How a sale works

What the kit is, and what it is not

Two keys, two channels

Entry points

Pick your flavour

Building with an AI agent

Next steps