REST API Client

The REST API client provides typed functions that wrap Ecwid REST API endpoints. All functions use GET requests, native fetch, and automatically attach the Bearer token from your initStorefrontApi() config.

TIP

You must call initStorefrontApi() before using any of these functions. See Setup.

Products

searchProducts

Search for products in a store. Ecwid API docs →

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

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

Params

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

Response

SearchProductsResponse // PaginatedResponse<Product>

---

getProduct

Fetch a single product by ID. Ecwid API docs →

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

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

Params

GetProductParams // { productId: number }

Response

GetProductResponse // Product

---

downloadProductFile

Download a product file (e-goods). Ecwid API docs →

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

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

Params

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

Response

DownloadProductFileResponse // Blob

---

searchProductVariations

Search variations (combinations) for a product. Ecwid API docs →

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

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

Params

SearchProductVariationsParams // { productId: number }

Response

SearchProductVariationsResponse // ProductCombination[]

---

getProductVariation

Get a single product variation. Ecwid API docs →

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

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

Params

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

Response

GetProductVariationResponse // ProductCombination

---

searchProductTypes

Get all product types (classes) in the store. Ecwid API docs →

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

const types = await searchProductTypes()

Params: none

// Response
SearchProductTypesResponse // ProductType[]

---

getProductType

Get a single product type. Ecwid API docs →

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

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

Params

GetProductTypeParams // { classId: number }

Response

GetProductTypeResponse // ProductType

---

searchProductBrands

Search product brands in the store. Ecwid API docs →

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

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

Params

SearchProductBrandsParams // optional — limit, offset, etc.

Response

SearchProductBrandsResponse // PaginatedResponse<ProductBrand>

Categories

searchCategories

Search categories in the store. Ecwid API docs →

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

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

Params

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

Response

SearchCategoriesResponse // PaginatedResponse<Category>

---

searchCategoriesByPath

Search categories by a delimiter-separated path string. Ecwid API docs →

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

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

Params

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

Response

SearchCategoriesByPathResponse // PaginatedResponse<Category>

Store Profile

getStoreProfile

Get basic store information: settings, location, email, etc. Ecwid API docs →

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

const profile = await getStoreProfile()

Params

GetStoreProfileParams // optional

Response

GetStoreProfileResponse // StoreProfile

Reviews

getReviews

Get product reviews from the store. Returns published reviews when accessed with a public token. Ecwid API docs →

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

GetReviewsResponse // PaginatedResponse shape with inline review item type

See Ecwid API docs for the full review object shape.

Shared Types

PaginatedResponse<T>

All search/list endpoints return this shape:

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

Constants

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 for all values.

Import from @lightspeed/ecom-headless:

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

await searchProducts({ sortBy: SortByValues.PRICE_ASC })

Related

• Storefront JS API — Cart, customer, callbacks, utility methods
• Examples — Real-world composable patterns
• Ecwid REST API Reference — Full endpoint documentation