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 — from fetching products to managing carts and initiating checkout. Install it once, wire up your API key in a server-only module, and call methods from your server boundary.

Install the package

npm install @quickshops/sdk

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 in client components, hooks, or any file marked "use client". The API key must stay on the server.

Create a server-only client

Instantiate the SDK once in a dedicated server-only file. In Next.js, add import "server-only" so the module cannot be pulled into client bundles.

lib/quickshops.ts

import "server-only";

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

export const qs = new Quickshops({
  bearerAuth: process.env.HEADLESS_API_KEY!,
});

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.store.storeGet()`	—	`GET /products/store`
`qs.products.productsGetAll()`	—	`GET /products`
`qs.products.productsGetById({ productId })`	`{ productId }`	`GET /products/:productId`
`qs.cart.cartCreate()`	—	`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 })`	`{ cartId }`	`POST /checkout/session`
`qs.subscription.subscriptionCreatePortalSession({ memberSessionId })`	`{ memberSessionId }`	`POST /subscription/portal`

SDK response shapes

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

const { data: store } = await qs.store.storeGet();
const { data: products } = await qs.products.productsGetAll();
const { data: cart } = await qs.cart.cartCreate();

Cart data includes id, storeId, lines (productId + quantity), 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, paymentsConfigured, optional templateKey, and templateTexts. Checkout session data is { url: string }.

Next steps

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

Package structure

Create a server-only client

Constructor options

Passing data to the browser safely

Method reference

SDK response shapes

Next steps

Framework guides

Error handling

API reference

​Install the package

​Package structure

​Create a server-only client

​Constructor options

​Passing data to the browser safely

​Method reference

​SDK response shapes

​Next steps

Framework guides

Error handling

API reference

Install the package

Package structure

Create a server-only client

Constructor options

Passing data to the browser safely

Method reference

SDK response shapes

Next steps