Installation
Install the SDK using your preferred package manager. npm will always resolve to the latest published version.Quick Start
To begin using the SDK, you need to initialize theTybrite client with your API key.
Configuration Options
TheTybrite constructor accepts a configuration object to customize the client behavior:
Automatic Retries
The SDK automatically retries requests that fail for transient reasons — network errors and the HTTP statuses429, 500, 502, 503, and 504 — using exponential backoff with jitter
(and honoring a Retry-After header when the API sends one). By default it makes up to 2
retries; tune or disable this with MAX_RETRIES.
GET,PUT, andDELETEare safe to repeat and are always retried.POSTandPATCHare retried on an error status only when you send anIdempotency-Keyheader. The API deduplicates those operations server-side (order creation, order updates, and payment initialization), so a retry returns the original result instead of acting twice. APOST/PATCHwithout an idempotency key is retried only when the connection fails outright (the request never reached the server, so no work could have happened) — never after the server has responded.
Two-Token Security Model
The Tybrite API uses two parallel authentication mechanisms. Most endpoints need only the API key, but customer-scoped operations require both a publishable API key (to identify your store) and a customer session token (to identify the shopper).-
API key (
Authorizationheader) — authenticates your application- Publishable keys (
tybrite_pk_*) — safe for browsers; read-only for sensitive data - Secret keys (
tybrite_sk_*) — server-side only; full read/write access
- Publishable keys (
-
Customer session token (
xAuthTokenparameter) — authenticates an end customer- Obtained from
client.authentication.login,verifyOtp, orregister - Required for customer-scoped operations (cart, wishlist, profile, gift cards, messaging)
- The resolved customer must match the
customer_idin the request, otherwise the API returns403
- Obtained from
Combining both tokens
Basic Usage
Once initialized, you can access various commerce services through the client instance.Response Codes
Every service in the SDK follows the same response-code contract, so you can centralize your error handling:
All errors share a single response shape:
ApiError you can catch:
Post-Processing Warnings on Orders
Order creation may include a
post_processing_warnings array in the response when gift card redemption or stock reduction partially fails. The order is still recorded — clients should check this array and surface warnings to customers or operators. See the OrdersService docs for details.Cursor-Based Pagination
For high-performance, stable scrolling through large datasets, Tybrite uses cursor-based pagination. This ensures consistent results even if data changes between requests. When a query supports cursor pagination, it will return apagination object along with the results. You can pass the next_cursor property to subsequent requests to fetch the next page:
Service Overview
The SDK exposes 17 services, each accessible as a property on theTybrite client. The “Customer auth?” column indicates whether the customer session token (xAuthToken) is required for at least some methods.
Building a marketplace? When a deployment runs as a marketplace, you authenticate the storefront with a marketplace operator key. The catalog services (
products, taxonomy, search) then return data aggregated across every active merchant — pass storeId to narrow them to a single merchant’s shop page. Use client.marketplace.getMarketplaceInfo for the marketplace’s identity and branding (or one merchant’s full store information), and client.marketplace to check out a single cart spanning multiple merchants with one payment that is split to each merchant automatically. See the Marketplace reference.Currency. Each store sets its own currency, returned as
store.default_currency (with the accepted list in store.currencies) from client.system.getStoreInfo. Catalog prices are expressed in that currency, so there’s no separate currency endpoint to call. See the Currency guide for single- and multi-currency storefronts.Next Steps
Now that you have initialized the client, explore the most commonly used services:Products
Manage your product catalog, categories, and inventory.
Orders
Handle the full lifecycle of commerce orders.
Customers
Manage customer profiles and analytics.
Authentication
Secure customer sessions and authentication flows.
Cart & Wishlist
Persistent cart and wishlist tied to customer sessions.
System & Store
Monitor health status and retrieve comprehensive store metadata.
Marketplace
Aggregate many merchants, run a unified multi-merchant checkout, and split payments automatically.

