Headless API

@lightspeed/ecom-headless is a typed TypeScript client for accessing Ecwid store data. It wraps two official Ecwid APIs into a single package with type safety, automatic authentication, and a consistent developer experience.

API Surface

The package provides typed wrappers for two distinct Ecwid APIs:

	REST API Client	Storefront JS API
Wraps	Ecwid REST API	Ecwid Storefront JS API
Runs in	Browser + Node.js	Browser only
What it does	Fetch portable products, categories, store profile, reviews	Session-aware Catalog/Product/Favorites data, cart, customer, navigation, events
How it works	Typed fetch wrapper with auto Bearer token	Promise wrappers around callback-based window.Ecwid methods

REST calls use initStorefrontApi(). Browser-only Storefront calls use the already loaded Ecwid widget and do not require package initialization.

Installation

npm install @lightspeed/ecom-headless

Setup

Before using any API function, initialize the client with a public token:

import { initStorefrontApi } from '@lightspeed/ecom-headless'

await initStorefrontApi({
  publicToken: 'YOUR_PUBLIC_TOKEN',
  storeId: 12345,
})

If you omit storeId, it is auto-detected from window.Ecwid. This only works in a browser after the Ecwid storefront widget has loaded. In Node.js, or if initialization runs before window.Ecwid is available, you must pass storeId explicitly.

ApiConfig

Property	Type	Required	Description
publicToken	string	Yes	Public access token for the store API
storeId	number	No	Store ID. If omitted, it is auto-detected from window.Ecwid in a browser context after the storefront widget loads; required in Node.js and before window.Ecwid is available
baseURL	string	No	API base URL. Defaults to https://app.ecwid.com/api/v3/

TIP

In a Crane theme, you get the public token and store ID from the Crane runtime via useInstantsiteJsApi(). See the Examples page for a ready-to-use init composable that wires this up.

getApiConfig

After initialization, you can retrieve the resolved config:

import { getApiConfig } from '@lightspeed/ecom-headless'

const config = getApiConfig()
// { publicToken: '...', storeId: 12345, baseURL: 'https://app.ecwid.com/api/v3/' }

Throws an error if called before initStorefrontApi().

Entry Points

The package provides four entry points for tree-shaking:

Import Path	What It Provides
@lightspeed/ecom-headless	Everything — REST functions, storefront methods, Catalog/Products/Favorites/Cart/Customer namespaces, constants, types
@lightspeed/ecom-headless/api	REST API functions only
@lightspeed/ecom-headless/storefront	Storefront JS API wrappers only
@lightspeed/ecom-headless/types	TypeScript types only (empty at runtime)

Next Steps

• REST API Client — Products, categories, store profile, reviews
• Storefront JS API — Cart, customer, callbacks, utility methods
• Examples — Real-world composable patterns