Skip to main content

TypeScript SDK

The official TypeScript SDK provides a fully typed client for the Headless Commerce API.

Installation

npm install @headless-commerce/sdk

Quick Start

import { HeadlessCommerce } from '@headless-commerce/sdk';

// Admin client (server-side)
const admin = new HeadlessCommerce({
  secretKey: 'sk_test_your_key',
});

// Storefront client (client-side safe)
const storefront = new HeadlessCommerce({
  publishableKey: 'pk_test_your_key',
});

Usage Examples

List Products

const { data, has_more } = await storefront.products.list({
  status: 'active',
  limit: 20,
});
// data: Product[] — fully typed with autocompletion

Cart Flow

// Create a cart
const cart = await storefront.carts.create({
  session_id: 'guest-session-123',
});

// Add an item
await storefront.carts.addItem(cart.id, {
  variant_id: 'var_001',
  quantity: 2,
});

// Get cart with calculated totals
const updated = await storefront.carts.get(cart.id);
console.log(updated.summary.total);
// { amount: 78000, currency: "KRW" }

// Checkout
const order = await storefront.carts.checkout(cart.id, {
  email: '[email protected]',
  payment_provider: 'stripe',
  payment_method_id: 'pm_xxx',
});

Admin Operations

// Create a product with variants
const product = await admin.products.create({
  name: 'Classic T-Shirt',
  type: 'physical',
  status: 'draft',
  options: [
    { name: 'Size', values: ['S', 'M', 'L'] },
    { name: 'Color', values: ['Black', 'White'] },
  ],
});

// Auto-pagination
for await (const order of admin.orders.listAll({ status: 'confirmed' })) {
  console.log(order.number);
}

Configuration

OptionTypeRequiredDescription
secretKeystring*Secret API key for server-side usage
publishableKeystring*Publishable key for client-side usage
baseUrlstringNoCustom API base URL (default: https://api.headlesscommerce.io/v1)
One of secretKey or publishableKey is required.