> 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/rest-api-client.md).

# REST API Client

The REST API client provides typed functions that wrap [Ecwid REST API](https://docs.ecwid.com/api-reference) endpoints. All functions use GET requests, native `fetch`, and automatically attach the Bearer token from your `initStorefrontApi()` config.

{% hint style="info" %}
You must call `initStorefrontApi()` before using any of these functions. See [Setup](https://ecwid.github.io/crane/headless-api/#setup).
{% endhint %}

### Products <a href="#products" id="products"></a>

#### `searchProducts` <a href="#searchproducts" id="searchproducts"></a>

Search for products in a store. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/search-products)

```typescript
import { searchProducts } from '@lightspeed/ecom-headless'

const response = await searchProducts({ keyword: 'laptop', enabled: true })
// response.items — Product[]
// response.total — total count
```

Params:

```typescript
SearchProductsParams // optional — keyword, category, limit, offset, sort, etc.
```

Response:

```typescript
SearchProductsResponse // PaginatedResponse<Product>
```

#### `getProduct` <a href="#getproduct" id="getproduct"></a>

Fetch a single product by ID. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/get-product)

```typescript
import { getProduct } from '@lightspeed/ecom-headless'

const product = await getProduct({ productId: 123 })
```

Params:

```typescript
GetProductParams // { productId: number }
```

Response:

```typescript
GetProductResponse // Product
```

#### `downloadProductFile` <a href="#downloadproductfile" id="downloadproductfile"></a>

Download a product file (e-goods). [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/product-files/download-product-file)

```typescript
import { downloadProductFile } from '@lightspeed/ecom-headless'

const file = await downloadProductFile({ productId: 123, fileId: 456 })
```

Params:

```typescript
DownloadProductFileParams // { productId: number, fileId: number }
```

Response:

```typescript
DownloadProductFileResponse // Blob
```

#### `searchProductVariations` <a href="#searchproductvariations" id="searchproductvariations"></a>

Search variations (combinations) for a product. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/product-variations/search-product-variations)

```typescript
import { searchProductVariations } from '@lightspeed/ecom-headless'

const variations = await searchProductVariations({ productId: 123 })
```

Params:

```typescript
SearchProductVariationsParams // { productId: number }
```

Response:

```typescript
SearchProductVariationsResponse // ProductCombination[]
```

#### `getProductVariation` <a href="#getproductvariation" id="getproductvariation"></a>

Get a single product variation. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/product-variations/get-product-variation)

```typescript
import { getProductVariation } from '@lightspeed/ecom-headless'

const variation = await getProductVariation({ productId: 123, combinationId: 456 })
```

Params

```typescript
GetProductVariationParams // { productId: number, combinationId: number }
```

Response:

```typescript
GetProductVariationResponse // ProductCombination
```

#### `searchProductTypes` <a href="#searchproducttypes" id="searchproducttypes"></a>

Get all product types (classes) in the store. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/product-types-and-attributes/search-product-types)

```typescript
import { searchProductTypes } from '@lightspeed/ecom-headless'

const types = await searchProductTypes()
```

Params: none

Response:

```typescript
SearchProductTypesResponse // ProductType[]
```

#### `getProductType` <a href="#getproducttype" id="getproducttype"></a>

Get a single product type. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/product-types-and-attributes/get-product-type)

```typescript
import { getProductType } from '@lightspeed/ecom-headless'

const type = await getProductType({ classId: 0 })
```

Params:

```typescript
GetProductTypeParams // { classId: number }
```

Response:

```typescript
GetProductTypeResponse // ProductType
```

#### `searchProductBrands` <a href="#searchproductbrands" id="searchproductbrands"></a>

Search product brands in the store. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/search-product-brands)

```typescript
import { searchProductBrands } from '@lightspeed/ecom-headless'

const brands = await searchProductBrands({ limit: 10 })
```

Params:

```typescript
SearchProductBrandsParams // optional — limit, offset, etc.
```

Response:

```typescript
SearchProductBrandsResponse // PaginatedResponse<ProductBrand>
```

### Categories <a href="#categories" id="categories"></a>

#### `searchCategories` <a href="#searchcategories" id="searchcategories"></a>

Search categories in the store. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/categories/search-categories)

```typescript
import { searchCategories } from '@lightspeed/ecom-headless'

const categories = await searchCategories({ lang: 'en' })
// categories.items — Category[]
```

Params:

```typescript
SearchCategoriesParams // optional — parent, limit, offset, lang, etc.
```

Response:

```typescript
SearchCategoriesResponse // PaginatedResponse<Category>
```

#### `searchCategoriesByPath` <a href="#searchcategoriesbypath" id="searchcategoriesbypath"></a>

Search categories by a delimiter-separated path string. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/categories/search-categories-by-path)

```typescript
import { searchCategoriesByPath } from '@lightspeed/ecom-headless'

const categories = await searchCategoriesByPath({
  path: 'Electronics/Phones/Smartphones',
  delimiter: '/',
})
```

Params:

```typescript
SearchCategoriesByPathParams // { path: string, delimiter: string }
```

Response:

```typescript
SearchCategoriesByPathResponse // PaginatedResponse<Category>
```

### Store Profile <a href="#store-profile" id="store-profile"></a>

#### `getStoreProfile` <a href="#getstoreprofile" id="getstoreprofile"></a>

Get basic store information: settings, location, email, etc. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/store-profile/get-store-profile)

```typescript
import { getStoreProfile } from '@lightspeed/ecom-headless'

const profile = await getStoreProfile()
```

Params:

```typescript
GetStoreProfileParams // optional
```

Response:

```typescript
GetStoreProfileResponse // StoreProfile
```

### Reviews <a href="#reviews" id="reviews"></a>

#### `getReviews` <a href="#getreviews" id="getreviews"></a>

Get product reviews from the store. Returns published reviews when accessed with a public token. [Ecwid API docs →](https://docs.ecwid.com/api-reference/rest-api/products/product-reviews/search-product-reviews)

```typescript
import { getReviews } from '@lightspeed/ecom-headless'

const response = await getReviews({ limit: 3 })
response.items.forEach(review => {
  console.log(`${review.rating}⭐ - ${review.review}`)
})
```

Params:

```
GetReviewsParams // optional — offset, limit, productId
```

Response:

```typescript
GetReviewsResponse // PaginatedResponse shape with inline review item type
```

See [Ecwid API docs](https://docs.ecwid.com/api-reference/rest-api/products/product-reviews/search-product-reviews) for the full review object shape.

### Shared Types <a href="#shared-types" id="shared-types"></a>

#### `PaginatedResponse<T>` <a href="#paginatedresponse-t" id="paginatedresponse-t"></a>

All search/list endpoints return this shape:

```typescript
interface PaginatedResponse<T> {
  total: number
  count: number
  offset: number
  limit: number
  items: T[]
}
```

#### Constants <a href="#constants" id="constants"></a>

| Constant       | Description                                                                                                                                                                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SortByValues` | Product sort options — `RELEVANCE`, `PRICE_ASC`, `PRICE_DESC`, `NAME_ASC`, `NAME_DESC`, `ADDED_TIME_DESC`, and more. See the [Ecwid search products docs](https://docs.ecwid.com/api-reference/rest-api/products/search-products) for all values. |

Import from `@lightspeed/ecom-headless`:

```typescript
import { SortByValues } from '@lightspeed/ecom-headless'

await searchProducts({ sortBy: SortByValues.PRICE_ASC })
```


---

# 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.