Skip to main content
The Tybrite TypeScript SDK provides a high-level, type-safe interface for interacting with the Tybrite API. It simplifies complex operations like order processing, inventory management, and customer analytics into easy-to-use methods.

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 the Tybrite client with your API key.

Configuration Options

The Tybrite 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 statuses 429, 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.
Retries are safe by design. The SDK never risks creating a duplicate resource:
  • GET, PUT, and DELETE are safe to repeat and are always retried.
  • POST and PATCH are retried on an error status only when you send an Idempotency-Key header. 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. A POST/PATCH without 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.
For order and payment calls, always pass a unique Idempotency-Key. It both guarantees exactly-once processing and unlocks automatic retries for those requests.

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).
  1. API key (Authorization header) — 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
  2. Customer session token (xAuthToken parameter) — authenticates an end customer
    • Obtained from client.authentication.login, verifyOtp, or register
    • Required for customer-scoped operations (cart, wishlist, profile, gift cards, messaging)
    • The resolved customer must match the customer_id in the request, otherwise the API returns 403
Customer write operations on cart and wishlist intentionally accept publishable keys, so browser code can call them directly. The xAuthToken is what proves the request belongs to a specific shopper.

Combining both tokens

Never embed secret keys (tybrite_sk_*) in browser bundles, mobile apps, or any client-side environment. Use publishable keys in clients and reserve secret keys for trusted server-side processes.

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:
The SDK surfaces these as a typed 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 a pagination object along with the results. You can pass the next_cursor property to subsequent requests to fetch the next page:
The following services currently support cursor-based pagination:

Service Overview

The SDK exposes 17 services, each accessible as a property on the Tybrite 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.