> For the complete documentation index, see [llms.txt](https://docs.ecwid.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecwid.com/site-themes/develop-site-themes/headless-api.md).

# 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 <a href="#api-surface" id="api-surface"></a>

The package provides typed wrappers for two distinct Ecwid APIs:

|                  | REST API Client                                        | Storefront JS API                                                |
| ---------------- | ------------------------------------------------------ | ---------------------------------------------------------------- |
| **Wraps**        | [Ecwid REST API](https://docs.ecwid.com/api-reference) | [Ecwid Storefront JS API](https://docs.ecwid.com/storefronts)    |
| **Runs in**      | Browser + Node.js                                      | Browser only                                                     |
| **What it does** | Fetch products, categories, store profile, reviews     | Cart management, customer data, page navigation, event callbacks |
| **How it works** | Typed `fetch` wrapper with auto Bearer token           | Promise wrappers around callback-based `window.Ecwid` methods    |

Both sides share a single initialization call.

### Installation <a href="#installation" id="installation"></a>

```bash
npm install @lightspeed/ecom-headless
```

### Setup <a href="#setup" id="setup"></a>

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

```typescript
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` <a href="#apiconfig" id="apiconfig"></a>

| 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/`                                                                                                                        |

{% hint style="success" %}
In a Crane theme, you get the public token and store ID from the Crane runtime via `useInstantsiteJsApi()`. See the [Examples](https://ecwid.github.io/crane/headless-api/examples) page for a ready-to-use init composable that wires this up.
{% endhint %}

#### `getApiConfig` <a href="#getapiconfig" id="getapiconfig"></a>

After initialization, you can retrieve the resolved config:

```typescript
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 <a href="#entry-points" id="entry-points"></a>

The package provides four entry points for tree-shaking:

| Import Path                            | What It Provides                                                                            |
| -------------------------------------- | ------------------------------------------------------------------------------------------- |
| `@lightspeed/ecom-headless`            | Everything — REST functions, storefront methods, 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)                                                    |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ecwid.com/site-themes/develop-site-themes/headless-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.