Build your own Storefront
The PosNova Headless SDK provides a lightweight, type-safe interface to connect your custom frontend to our high-performance eCommerce kernel.
Edge Ready
Optimized for Vercel, Netlify, and Edge functions.
Hashed Keys
Keys are SHA-256 hashed at rest and instantly revocable.
Full Typed
End-to-end TypeScript support for all resources.
Installation
Authentication
You can generate API keys in your Organization Settings. Test keys allow you to iterate safely without affecting production metrics.
pn_live_...Accesses live data and real orders.
pn_test_...Safe for local testing and CI/CD.
import { PosNova } from '@posnova/sdk';
const sdk = new PosNova({
apiKey: 'pn_live_...',
// Optional for self-hosted instances
supabaseUrl: process.env.SUPABASE_URL,
supabaseAnonKey: process.env.SUPABASE_ANON_KEY
});API Reference
Storefront Discovery
Every headless experience starts with fetching the store profile. This provides the tenantId required for all catalog operations.
Usage
await sdk.getStore('subdomain');Response Profile
- tenantId number
- theme Object
- seo Object
Catalog Management
getProducts()
List products with support for offset pagination, price sorting, and category filters.
await sdk.getProducts({
tenantId: 123,
limit: 10,
offset: 0,
sortBy: 'price-desc'
});getProduct()
Retrieve a single product by its slug, including full variation trees and specifications.
await sdk.getProduct({
tenantId: 123,
slug: 'premium-shoes'
});Customer & Auth
Integrated Auth
The SDK automatically hooks into Supabase Auth. Once a user is logged in, you can fetch their profile and sync wishlists with a single call.
- Auto-session handling
- Wishlist database sync
- Order history access
await sdk.getCustomerProfile();await sdk.syncWishlist(items);Orders & Checkout
The SDK is optimized for reads — store discovery, catalog and customer data. To create orders from your custom frontend, call the REST API from your server: prices and totals are always re-computed server-side, so a tampered client can never change what gets charged.
const res = await fetch("https://api.posnova.store/v1/orders", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.POSNOVA_API_KEY}`, // server-only!
"Content-Type": "application/json",
},
body: JSON.stringify({
items: cart.map(({ productId, variantId, qty }) => ({
product_id: productId, variant_id: variantId, quantity: qty,
})),
customer: { name, phone, city },
payment_method: "COD",
}),
});
const { data } = await res.json(); // { order_id, receipt_number, total, … }COD and OFFLINE orders are supported via the API. Card and gateway payments (Stripe, SSLCommerz, PayPal) must run through the hosted storefront checkout, which handles gateway callbacks and payment verification for you. See the Orders API reference for the full request schema.