Getting Started
Installation & Setup
Install the SDK and create your first storefront client
Install
npm install @behio/storefront-sdkCreate Client
import { BehioStorefront } from '@behio/storefront-sdk';
const client = new BehioStorefront({
apiKey: 'pk_live_your_key',
});Options
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | required | Your public API key (pk_live_...) |
locale | string | none | Default locale for all requests |
currency | string | none | Default currency. See Currency for runtime switching |
shopDomain | string | none | Domain this storefront serves (sent as X-Shop-Domain). Only for one deployment serving several domains with an "all domains" key in SSR |
timeout | number | 30000 | Request timeout in ms |
retries | number | 1 | Retry count on 5xx / network errors |
retryDelay | number | 1000 | Base delay between retries in ms |
fetch | typeof fetch | globalThis.fetch | Custom fetch implementation (for SSR) |
visitorIp | string | () => string | none | Real visitor IP for SSR, sent as X-Behio-Visitor-Ip so the backend rate-limits per visitor instead of per rendering server. The Next.js adapter (getBehio from @behio/storefront-sdk/next) fills it automatically from the request headers, so you only set it for custom server setups. The backend only trusts the header from allow-listed hosting IPs |
throwOnAvailabilityError | boolean | false | Throw availability failures (429, 5xx, network, timeout) instead of returning them in SdkResult.error. Business outcomes (400, 401, 404, ...) keep the tuple shape. Recommended true for server-rendered catalog clients, so a rate limit or outage surfaces as an error page instead of silently rendering an empty catalog. Available since 1.8.0 |
Modules
client.catalog // Products, categories, search, bundles
client.auth // Register, login, tokens
client.cart // Cart items, discounts, gift cards
client.checkout // Create orders
client.orders // Order list, detail, tracking
client.customer // Profile, addresses
client.wishlist // Wishlist management
client.reviews // Product reviews
client.returns // Return requests
client.consent // Cookie consent (GDPR)
client.quotes // B2B quotes
client.pages // CMS pages