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.
Which methods are retried depends on whether repeating the request could create a second resource:
  • GET, PUT, and DELETE produce the same result when repeated, 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.
A unique Idempotency-Key on order and payment calls does two things: it guarantees exactly-once processing, and it makes those requests eligible for automatic retry.

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

Commerce services are reached as properties on the initialized client.

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

List endpoints paginate by cursor rather than by offset, so a row inserted or removed between requests does not shift the page boundary and cause an item to repeat or be skipped. A paginated query returns a pagination object alongside the results. Its next_cursor property fetches the following page:
The services whose list methods accept a cursor:

Service Overview

Each service is accessible as a property on the Tybrite client. The most commonly used ones are below; the API reference covers the full set, including returns, disputes, reviews, tax, B2B, and the ingestion and sandbox tooling. 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

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.