Install and configure the Quickshops TypeScript SDK

Developers only. Selling through the built-in Quickshops storefront does not require the SDK. Start with the Quickstart if you’re setting up a store as a seller.The SDK requires a Pro plan API key from Settings → API keys. See Authentication for setup.

The Quickshops TypeScript SDK gives you a typed, server-side client for every API operation your storefront needs. For custom storefronts (Lovable / v0 / Next.js), start with useStore() from @quickshops/sdk so you do not hand-roll redirects, cart cookies, or success-page session lookups.

Install the package

npm install @quickshops/sdk

Requires @quickshops/sdk@1.1.0+ for useStore() plus the @quickshops/sdk/react export (Storefront composition primitives).

`useStore()` (recommended for storefronts)

lib/quickshops.ts

import "server-only";
import { useStore } from "@quickshops/sdk";

export const store = useStore();

app/actions.ts

"use server";

import { redirect } from "next/navigation";
import { store } from "@/lib/quickshops";

export async function homeData() {
  return store.loadCatalog();
}

export async function buy(productId: string) {
  const { url } = await store.buyNow({ productId });
  redirect(url);
}

useStore reads HEADLESS_API_KEY, optional HEADLESS_API_URL, and SITE_URL from the environment. It returns buyNow, loadCatalog, getCheckoutSession, cart cookie helpers, and more. It is a server factory, not a React hook. Keep qk_ on the server and pass data / Server Actions into @quickshops/sdk/react. There is no publishable browser API key.

One-prompt install

Paste into Lovable, v0.dev, Cursor, or Bolt (Next.js App Router). Set HEADLESS_API_KEY, optional HEADLESS_API_URL, and SITE_URL on the host after it scaffolds.

Build a Next.js App Router TypeScript storefront that sells via Quickshops.

SSR-first for SEO (Server Components for catalog/PDP). No publishable API keys.
Install: npm add @quickshops/sdk server-only react

Server: use ONLY useStore from @quickshops/sdk (import "server-only").
Client UI: use @quickshops/sdk/react composition primitives (Storefront.Provider, Storefront.Product slots, BuyButton, CheckoutSuccess).
Use shadcn-style theme tokens already in the project (bg-primary, text-card-foreground, etc.) — do not invent a parallel design system.
Do NOT raw-fetch api.quickshops.app from the browser. Do NOT invent pk_ / publishable keys.
Do NOT hand-roll successUrl/cancelUrl or cart cookies.
Do NOT put HEADLESS_API_KEY in client components or NEXT_PUBLIC_*.
useStore is a server factory, not a React hook — never import it in "use client" files.

Env (server only):
- HEADLESS_API_KEY=qk_...
- HEADLESS_API_URL=https://api.quickshops.app (optional)
- SITE_URL=https://this-site-absolute-https-origin

lib/quickshops.ts:
import "server-only";
import { useStore } from "@quickshops/sdk";
export const store = useStore();

Default flow = buy-now (no cart cookie):
1. Home: store.loadCatalog() → Storefront.Provider with toStoreProducts(products) and actions={{ buy: buyProduct }} → Storefront.Grid
2. Buy action: store.buyNow({ productId }) → redirect(url)
3. Success: CheckoutSuccess with store.getCheckoutSession(session_id); store.clearCartId(await cookies())

Optional cart only if needed: store.addToCart(await cookies(), { productId }), store.checkoutCart({ cartId }).

Handle error codes: CART_EMPTY, CART_MIXED_TYPES, PAYMENTS_NOT_CONFIGURED, STORE_UNPUBLISHED, RATE_LIMITED.

Ship a working SSR storefront I can set env vars on and complete a test purchase with.

Optional agent skill:

npx skills add valtterisa/quickshops --skill quickshops-headless-storefront

React components (`@quickshops/sdk/react`)

Prebuilt shadcn-style composition primitives that never hold your API key. They use your app’s theme CSS variables (--primary, --card, …). Wire Server Actions through Storefront.Provider:

import { Storefront, toStoreProducts } from "@quickshops/sdk/react";

<Storefront.Provider products={toStoreProducts(products)} actions={{ buy: buyProduct }}>
  <Storefront.Grid />
</Storefront.Provider>

Full guide: React components.

Package structure

@quickshops/sdk is the official TypeScript client for the Quickshops Headless API. Instantiate it only in server-only modules (loaders, actions, API routes) and pass response data to your UI.

Never construct Quickshops or call useStore() in client components, hooks, or any file marked "use client". The API key must stay on the server.

Create a server-only client

Prefer useStore(). Or construct the low-level client manually:

lib/quickshops.ts

import "server-only";

import { Quickshops } from "@quickshops/sdk";

export const qs = new Quickshops({
  bearerAuth: process.env.HEADLESS_API_KEY!,
  serverURL: process.env.HEADLESS_API_URL ?? "https://api.quickshops.app",
});

Your API key must start with qk_ and is sent as Authorization: Bearer qk_... on every request.

Constructor options

import { Quickshops } from "@quickshops/sdk";

const qs = new Quickshops({
  bearerAuth: process.env.HEADLESS_API_KEY!,
  serverURL: "https://api.quickshops.app",
});

The REST API base URL is https://api.quickshops.app/v1. The SDK serverURL defaults to https://api.quickshops.app and adds /v1 to each request path automatically. For local development against a running API instance:

const qs = new Quickshops({
  bearerAuth: process.env.HEADLESS_API_KEY!,
  serverURL: "http://localhost:3006",
});

Passing data to the browser safely

Fetch with the SDK on the server, then pass only the response data to client components as props or through your own API routes. Never pass the Quickshops instance, the raw API key, or process.env.HEADLESS_API_KEY to the client.

// app/page.tsx — Server Component
import { qs } from "@/lib/quickshops";
import { ProductList } from "./product-list";

export default async function Page() {
  const { data: products } = await qs.products.productsGetAll();
  return <ProductList products={products} />;
}

// product-list.tsx — Client Component
"use client";

type Product = { id: string; name: string };

export function ProductList({ products }: { products: Product[] }) {
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

Method reference

All SDK methods are async and map to REST endpoints on the API base URL. Responses are wrapped in { data: ... } unless noted otherwise.

Method	Request	API endpoint
`qs.health.healthCheck()`	—	`GET /health`
`qs.catalog.catalogGet()`	—	`GET /catalog`
`qs.store.storeGet()`	—	`GET /products/store`
`qs.products.productsGetAll()`	—	`GET /products`
`qs.products.productsGetById({ productId })`	`{ productId }`	`GET /products/:productId`
`qs.cart.cartCreate(request?)`	optional `{ lines: [{ productId, quantity }] }`	`POST /cart`
`qs.cart.cartGet({ cartId })`	`{ cartId }`	`GET /cart/:cartId`
`qs.cart.cartAddLine({ cartId, body })`	`{ cartId, body: { productId, quantity } }`	`POST /cart/:cartId/lines`
`qs.cart.cartUpdateLine({ cartId, productId, body })`	`{ cartId, productId, body: { quantity } }`	`PATCH /cart/:cartId/lines/:productId`
`qs.cart.cartRemoveLine({ cartId, productId })`	`{ cartId, productId }`	`DELETE /cart/:cartId/lines/:productId`
`qs.cart.cartClear({ cartId })`	`{ cartId }`	`DELETE /cart/:cartId`
`qs.checkout.checkoutCreateSession({ ... })`	`{ cartId }` or `{ productId, quantity? }` plus optional `successUrl` / `cancelUrl`	`POST /checkout/session`
`qs.checkout.checkoutGetSession({ sessionId })`	`{ sessionId }`	`GET /checkout/sessions/:sessionId`
`qs.subscription.subscriptionCreatePortalSession({ memberSessionId })`	`{ memberSessionId }`	`POST /subscription/portal`

SDK response shapes

Every method returns a response object. Unwrap the payload with .data:

const { data: catalog } = await qs.catalog.catalogGet();
const { data: store } = await qs.store.storeGet();
const { data: products } = await qs.products.productsGetAll();
const { data: cart } = await qs.cart.cartCreate({
  lines: [{ productId: "prod_...", quantity: 1 }],
});

Prefer catalogGet() for home pages — it returns { store, products } in one call. Cart data includes id, storeId, lines (productId, quantity, optional expanded product), and totals (subtotal, total, currency). Product data items use id (not _id), plus storeId, name, description, priceInCents, currency, type ("digital" or "subscription"), billingInterval, imageUrl, isActive, category, and details. Store data includes id, slug, name, description, logoUrl, isPublished, currency, contact/SEO fields, theme, paymentsConfigured, optional templateKey, and templateTexts. Checkout create data is { url: string, sessionId: string }. Session status data includes paymentStatus, amountTotal, currency, customerEmail, and lineItems.

Next steps

React components

Storefront composition primitives and CheckoutSuccess.

Framework guides

Setup examples for Next.js, Remix, and other frameworks.

Error handling

Handle API errors and retries in your app.

API reference

Full REST API documentation.

Get Started

Your Store

Products & Sales

Integrations

Developers

Install and configure the Quickshops TypeScript SDK

Install the package

`useStore()` (recommended for storefronts)

One-prompt install

React components (`@quickshops/sdk/react`)

Package structure

Create a server-only client

Constructor options

Passing data to the browser safely

Method reference

SDK response shapes

Next steps

React components

Framework guides

Error handling

API reference

​Install the package

​useStore() (recommended for storefronts)

​One-prompt install

​React components (@quickshops/sdk/react)

​Package structure

​Create a server-only client

​Constructor options

​Passing data to the browser safely

​Method reference

​SDK response shapes

​Next steps

React components

Framework guides

Error handling

API reference

Install the package

`useStore()` (recommended for storefronts)

One-prompt install

React components (`@quickshops/sdk/react`)

Package structure

Create a server-only client

Constructor options

Passing data to the browser safely

Method reference

SDK response shapes

Next steps