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
| Option | Type | Required | Description |
|---|
secretKey | string | * | Secret API key for server-side usage |
publishableKey | string | * | Publishable key for client-side usage |
baseUrl | string | No | Custom API base URL (default: https://api.headlesscommerce.io/v1) |
One of secretKey or publishableKey is required.