@behio/storefront-sdk

Headless e-commerce SDK for building custom storefronts.

Behio gives you a complete e-commerce backend — products, inventory, orders, customers, discounts, multi-currency, multi-language — and lets you design the storefront however you want. No themes, no templates, no vendor lock-in.

Why Behio?

• You own the frontend. Next.js, React, Vue, Nuxt, Astro, or plain JS — the backend doesn't care.
• Production-ready in minutes. Catalog, cart, checkout, customer accounts, orders, CMS, discount codes, gift cards, loyalty programs, and more.
• Built for developers. Full TypeScript types, auto-completing, modern React hooks with TanStack Query.
• Scale-ready. Redis caching, rate limiting, webhooks, atomic checkout (no double-spend, no overselling).

Install

npm install @behio/storefront-sdk

Quick Start

import { BehioStorefront } from '@behio/storefront-sdk';

const storefront = new BehioStorefront({
  apiKey: 'pk_live_your_key',
});

// Fetch products
const { items } = await storefront.catalog.getProducts({ limit: 12 });

// Add to cart
await storefront.cart.addItem({ productId: items[0].id, quantity: 1 });

// Checkout
const order = await storefront.checkout.createOrder({
  email: '[email protected]',
  shippingAddress: { firstName: 'Jan', lastName: 'Novak', street: 'Vodickova 12', city: 'Praha', zip: '11000', country: 'CZ' },
});

React Hooks

import { BehioProvider, useProducts, useCart, useAddToCart } from '@behio/storefront-sdk/react';

function App() {
  return (
    <BehioProvider client={storefront}>
      <ProductList />
    </BehioProvider>
  );
}

function ProductList() {
  const { data, isLoading } = useProducts({ limit: 12 });
  const addToCart = useAddToCart();

  if (isLoading) return <div>Loading...</div>;

  return data.items.map(p => (
    <div key={p.id}>
      <h3>{p.name} — {p.price} {p.currency}</h3>
      <button onClick={() => addToCart.mutateAsync({ productId: p.id, quantity: 1 })}>
        Add to Cart
      </button>
    </div>
  ));
}

What's Included

SDK Modules

| Module | Description | |--------|-------------| | catalog | Products, categories, labels, search, filters, bundles, cross-sell, promotions | | auth | Register, login, logout, password reset, token refresh | | cart | Items, discounts, gift cards, bundles, cart merge | | checkout | Create orders with atomic stock/payment validation | | orders | List, detail, tracking, cancel | | customer | Profile, addresses, password change | | wishlist | Add, remove, check | | reviews | Submit, list, vote helpful | | addresses | Address autocomplete with debounce hook | | returns | Submit return requests | | consent | Cookie consent (GDPR) | | quotes | B2B quote requests | | pages | CMS pages |

React Hooks (30+)

useProducts · useProduct · useCategories · useCategoryProducts · useFeaturedProducts · useLabels · useProductSearch · useFilters · useBundles · useBundle · useCrossSell · useProductPromotions · useGiftCardBalance · useCart · useAddToCart · useUpdateCartItem · useRemoveCartItem · useCheckout · useOrders · useOrder · useOrderTracking · useCustomerProfile · useAddresses · useAddressAutocomplete · useWishlist · useProductReviews · useSubmitReview · useShopInfo · useShopSeo · useCartCount

Framework Support

• Next.js — Server components + client hooks, SSR ready
• React + Vite — Standard SPA setup
• Nuxt 3 — Composables with SSR
• Vue + Vite — Provide/inject pattern
• Vanilla JS — Works in any runtime (Node.js, Deno, Bun, Cloudflare Workers)

Built-in Features

• Automatic JWT token refresh on 401
• Configurable retry with backoff (5xx, 429)
• Rate limit tracking and warnings
• Request/response interceptors
• Event system (auth, cart, order lifecycle)
• Cart session persistence

Documentation

Full API reference, framework guides, and examples:

sdk.behio.com

License

MIT