Search products
GET https://app.ecwid.com/api/v3/{storeId}/products
Required access scopes
Your app must have the following access scopes to make this request: read_catalog
Path params
All path params are required.
storeId
number
Ecwid store ID.
Query params
All query params are optional.
productId
number
Internal IDs of Ecwid products separated by a comma. If this field is specified, other search parameters are ignored.
sku
string
Product or variation SKU. Ecwid will return details of a product containing that SKU, if SKU value is an exact match. If SKU is specified, other search parameters are ignored, except for product ID.
keyword
string
Search term. Add * at the end of the keyword to disable the exact match search. Search supports any language enabled in the store and specified in the lang param.
Supported fields:
namedescriptionSKU(including variations SKU)optionscategorynamegalleryimage descriptionsattributesvalues (except for hidden attributes). Any special characters must be URI-encoded.
searchMethod
string
Extension to keyword.
One of:
STOREFRONT – emulates search on the storefront
CP – emulates search in Ecwid admin
externalReferenceId
string
Product ID in linked POS. Includes both product IDs and product variation IDs.
category
string
Search term for finding products assigned to a specific category by its ID.
categories
string
Search term for finding products assigned to specified category IDs. For example: 0,123456,138470508.
includeProductsFromSubcategories
boolean
Set true to get products from the subcategories of specified categories.
priceFrom
number
Minimum product price.
priceTo
number
Maximum product price.
createdFrom
number/string
Product creation date/time (lower bound). Supported formats: UNIX timestamp, datetime.
Examples: 1447804800, 2023-01-15 19:27:50
createdTo
number/string
Product creation date/time (upper bound). Supported formats: UNIX timestamp, datetime.
Examples: 1447804800, 2023-01-15 19:27:50
updatedFrom
number/string
Product creation date/time (lower bound). Supported formats: UNIX timestamp, date/time.
Examples: 1447804800, 2023-01-15 19:27:50
updatedTo
number/string
Product creation date/time (upper bound). Supported formats: UNIX timestamp, date/time.
Examples: 1447804800, 2023-01-15 19:27:50
sortBy
string
Sort order for found products. One of:
RELEVANCE (default)
DEFINED_BY_STORE_OWNER
ADDED_TIME_DESC
ADDED_TIME_ASC
NAME_ASC
NAME_DESC
PRICE_ASC
PRICE_DESC
UPDATED_TIME_ASC
UPDATED_TIME_DESC
When category search term is set, DEFINED_BY_STORE_OWNER is used automatically.
enabled
boolean
Set true to get only enabled products.
Set false to get only disabled products.
isGiftCard
boolean
Set true to get gift cards only.
Set false to receive gift cards only.
inStock
boolean
Set true to get only in-stock products.
Set false to get only out-of-stock products.
discountsAllowed
boolean
Set true to get only products with allowed discounts.
Set false to get only products where discounts are not allowed.
visibleInStorefront
boolean
Set true to get only products visible on the storefront.
Set false to get only hidden products.
isCustomerSetPrice
boolean
Set true to get only products with customer-defined prices.
Set false to get only products without customer-defined prices.
onsale
string
Set onsale to get only items currently on sale.
Set notonsale to get only items currently not on sale.
inventory
string
Set instock to get only in-stock products.
Set outofstock to get only out-of-stock products.
baseUrl
string
Set base URL for URLs in response. If not specified, Ecwid will use the main URL from store settings.
cleanUrls
boolean
Set true to force receiving clean URLs – catalog links without hashbang (/#!/).
By default Ecwid checks if this setting is enabled for the store and responds with matching URLs.
slugsWithoutIds
boolean
Set trueto receive product page slugs without IDs.
By default Ecwid checks if this setting is enabled for the store and responds with matching URLs.
option_{optionName}={optionValue}
string
Filter by product option name and one or several comma-separated values for that option. A product will appear in the response if it has an option with a specified name that has any of the specified values.
For example, a product has an option named Size with three values 24, 26, and 30. Then the following search term will find the product: option_Size=24,22. Even when the product doesn't have an option value 22.
attribute_{attributeName}={attributeValue}
string
Filter by product attribute name and one or several comma-separated values for that attribute. A product will appear in the response if it has an attribute with a specified name that has any of the specified values.
For example, a product has an attribute named Brand with an Ecwid value. Then the following search term will find the product: attribute_Brand=Ecwid,Lightspeed. Even when the product doesn't have a Lightspeed attribute value.
externalReferenceId
string
Search term for product ID from the connected POS system (Lightspeed X/R series).
offset
number
Offset from the beginning of the returned items list. Used when the response contains more items than limit allows to receive in one request.
Usually used to receive all items in several requests with multiple of a hundred, for example:
?offset=0 for the first request,
?offset=100, for the second request,
?offset=200, for the third request, etc.
limit
number
Limit to the number of returned items. Maximum and default value (if not specified) is 100.
responseFields
string
Limit JSON response by specific fields. If specified, all missing fields will be removed from the response body.
Example: ?responseFields=total,items(id,name,price,quantity)
Example of using responseFields param:
Headers
The Authorization header is required.
Authorization
Bearer secret_ab***cd
Access token of the application.
Response JSON
A JSON object with the following fields:
total
number
Total number of found items (might be more than the number of returned items).
count
number
Total number of items returned in the response.
offset
number
Offset from the beginning of the returned items list specified in the request.
limit
number
Maximum number of returned items specified in the request. Maximum and default value: 100.
items
Detailed information about returned products.
items
id
number
Internal unique product ID.
sku
string
Product SKU. Items with options can have several SKUs specified in the product variations.
quantity
number
Amount of product items in stock.
If the product has unlimited stock (unlimited is true), this field is not returned.
unlimited
boolean
Defines if the product has unlimited stock.
inStock
boolean
Defines if the product or any of its variations are in stock (quantity is more than 0).
name
string
Product name visible on the storefront.
nameTranslated
string
Available translations for the product name.
price
number
Base product price without any modifiers.
priceInProductList
number
Product price as it's shown on the storefront.
May differ from price if pre-selected product options or variations modify the price.
Does not include taxes
defaultDisplayedPrice
number
Product price as it's shown on the storefront for logged out customers with default location (store location). pre-selected product options or variations modify the price. Includes taxes
defaultDisplayedPriceFormatted
string
Formatted variant (curency symbol and delimeter settings) of defaultDisplayedPrice based on the store's format settings.
For example, €11,00
costPrice
number
Purchase price of the product in the specific order used for reports and profit calculations.
tax
object tax
Detailed information about product's taxes.
wholesalePrices
Sorted list of wholesale price tiers: "minimum quantity = price" pairs.
compareToPrice
number
Product pre-sale price with the same value as specified in Ecwid admin (without taxes), e.g. 40.
compareToPriceFormatted
string
Formatted display of compareToPrice with a currency symbol, e.g. €44,00.
Includes taxes when a store uses net prices (prices don't include taxes). Displayed as strikethrough price on the storefront.
compareToPriceDiscount
number
Discount from the sale price, e.g. -11.
compareToPriceDiscountFormatted
string
Formatted discount from the sale price, e.g. €11,00.
compareToPriceDiscountPercent
number
Discount percent from the sale price, e.g. -25.
compareToPriceDiscountPercentFormatted
string
Sale price discount percent (with percent sign), e.g. -25%.
defaultDisplayedCompareToPrice
number
Product pre-sale price including taxes, e.g. 44.
defaultDisplayedCompareToPriceFormatted
string
Formatted display of compareToPrice with a currency symbol, e.g. €44,00.
Includes taxes when a store uses net prices. Displayed as strikethrough price on the storefront.
defaultDisplayedCompareToPriceDiscount
number
Discount from the sale price, e.g. -11.
defaultDisplayedCompareToPriceDiscountFormatted
string
Formatted discount from the sale price, e.g. €11,00.
defaultDisplayedCompareToPriceDiscountPercent
number
Discount percent from the sale price, e.g. -25.
defaultDisplayedCompareToPriceDiscountPercentFormatted
string
Sale price discount percent (with percent sign), e.g. -25%.
lowestPriceSettings
isShippingRequired
boolean
Defines if the product requires shipping.
weight
number
Product weight in the units defined in store settings. If the product doesn't have weight, this field is not returned.
url
string
Link to the product details page on the storefront.
It is affected by page slug settings: customSlug has the highest priority, and if it's empty automgeneratedSlug is used.
autogeneratedSlug
string
Page slug generated for the product page URL automatically. If the product doesn't have custom slug, this field will be automatically updated whe the product's name is changed.
customSlug
string
Custom slug defined by the store owner. Affects product page URL.
created
string
Datetime of the product creation.
For example: 2024-07-30 10:32:37 +0000
updated
string
Datetime of the latest product change whether it was API call or a change made through Ecwid admin.
For example: 2024-07-30 10:32:37 +0000
createTimestamp
number
UNIX timestamp of the product creation. For example: 1427268654
updateTimestamp
number
UNIX timestamp of the latest product change whether it was API call or a change made through Ecwid admin. For example: 1427268654
productClassId
number
enabled
boolean
Defines if the product is enabled and visible on the storefront.
If false, the product can't be opened on the storefront or added to the cart.
options
Detailed list of product options.
Empty ([]) if no options are specified for the product.
warningLimit
number
Minimum amount of products in stock to trigger an automated "low stock" email notification for the store owner.
fixedShippingRateOnly
boolean
Legacy feature – see shipping field instead.
true if shipping cost for this product is calculated as 'Fixed rate per item' (managed under the "Tax and Shipping" section of the product management page in Ecwid Control panel). false otherwise.
With this option on, the fixedShippingRate field specifies the shipping cost of the product.
fixedShippingRate
number
Legacy feature – see shipping field instead.
When fixedShippingRateOnly is true, this field sets the product fixed shipping cost per item.
When fixedShippingRateOnly is false, the value in this field is treated as an extra shipping cost the product adds to the global calculated shipping
shipping
Shipping settings specific to the product.
defaultCombinationId
number
Identifier of the default product variation, which is defined by the default values of product options.
originalImage
Details about product main image.
galleryImages
Details about product gallery images (for updating alt tags and sort order).
description
string
Product description in HTML format. Scripts inside product descriptions are not supported.
descriptionTranslated
Available translations for the product description.
media
Details about product images and videos.
categoryIds
array of numbers
List of the category IDs the product belongs to.
categories
Detailed list of the category IDs the product belongs to.
defaultCategoryId
number
Default category ID of the product. If value is 0, then product does not have a default category and is not shown anywhere in storefront
seoTitle
string
Page title for search engines. Recommended length < 55 characters.
seoTitleTranslated
Translations for the SEO page title.
seoDescription
string
Page description for search engines. Recommended length < 160 characters.
seoDescriptionTranslated
Translations for the SEO page description.
favorites
Stats showing how many times the product was added to favorites on the storefront.
attributes
List of product attributes and their values.
files
Details about downloadable files attached to the product.
relatedProducts
List of related products displayed as "You may also like" products of the product.
combinations
Details about product variations.
dimensions
Product's dimensions.
volume
number
Product volume for calculations shipping costs, fractional number, 0 by default.
showOnFrontpage
number
Product index on the main storefront page starting with 1.
subscriptionSettings
Internal details for subscription products. Only available for payment methods developed by Ecwid team.
isSampleProduct
boolean
Defines sample product created by Ecwid. Sample products are unavailable for purchase.
isGiftCard
boolean
Defines if a product is a gift card.
subtitle
string
Small product description visible on category and product pages under the product title.
subtitleTranslated
Available translations for product subtitles.
discountsAllowed
boolean
Defines if Ecwid can apply discounts to the product.
externalReferenceId
string
External ID for products synced from external services, for example, POS.
outOfStockVisibilityBehaviour
boolean
Defines if a product is visible and/or can be pre-ordered when out-of-stock.
Requires enabled pre-orders on the store level: allowPreordersForOutOfStockProducts setting in /profile endpoint.
Supported values:
SHOW - Show out-of-stock products, but adding them to the cart is impossible.
HIDE - Hide out-of-stock products.
ALLOW_PREORDER - Show out-of-stock products and allow them to be added to the cart.
minPurchaseQuantity
number
Sets minimum product purchase quantity.
Default value is null.
maxPurchaseQuantity
number
Sets maximum product purchase quantity.
Default value is null.
reviewsCollectingAllowed
boolean
When true, allows to collect, check, and publish reviews for this product in store.
rating
number
Average rating from product reviews.
reviewsPublished
number
Number of reviews published by the store owner.
reviewsModerated
number
Number of reviews waiting for store owner's approval.
favorites
count
number
Total count the product was added to favorites on the storefront.
displayedCount
string
The number of likes visible on the storefront.
May differ from the count exceeds 1000 - it will show 1K instead of the precise number.
wholesalePrices
quantity
number
Number of product items on this wholesale tier.
price
number
Product price on the tier.
lowestPriceSettings
lowestPriceEnabled
boolean
Defines if the lowest price is enabled for the product and shown on the storefront.
manualLowestPrice
number
Manually entered lowest price for the last 30 days before any discounts or taxes applied.
defaultDisplayedManualLowestPrice
number
manualLowestPrice with taxes applied.
defaultDisplayedManualLowestPriceFormatted
string
Formatted display of defaultDisplayedManualLowestPrice using store format settings.
automaticLowestPrice
number
Automatically calculated lowest price for the last 30 days before any discounts or taxes applied. Read-only
defaultDisplayedAutomaticLowestPrice
number
automaticLowestPrice with taxes applied.
Read-only
defaultDisplayedAutomaticLowestPriceFormatted
string
Formatted display of defaultDisplayedAutomaticLowestPrice using store format settings.
Read-only
options
choices
shipping
type
string
One of: "GLOBAL_METHODS", "SELECTED_METHODS", "FLAT_RATE", "FREE_SHIPPING". "GLOBAL_METHODS" – all standard shipping methods set up in store settings; "SELECTED_METHODS" –
Ecwid will use enabledMethods and disabledMethods list to make shipping calculations; "FLAT_RATE" – sets flat rate for product's shipping, see flatRate field.
methodMarkup
number
Additional product shipping cost added to any shipping methods.
flatRate
number
Flat rate cost for shipping the product. If set, shipping costs for it will not be calculated.
disabledMethods
array of strings
enabledMethods
array of strings
originalImage
url
string
Link to the full-size main product image.
width
number
Width of the full-size main product image in px.
height
number
Height of the full-size main product image in px.
galleryImages
id
number
Internal ID for the gallery image.
url
string
Link to the gallery image image.
thumbnail
string
Link to the gallery image thumbnail resized to fit 160x160px container.
originalImageUrl
string
Link to the full-sized gallery image.
imageUrl
string
Link to the gallery image resized to fit 1200x1200px container.
hdThumbnailUrl
string
Link to the gallery image thumbnail resized to fit 800x800px container.
thumbnailUrl
string
Link to the gallery image thumbnail resized to fit 400x400px container.
smallThumbnailUrl
string
Link to the gallery image thumbnail resized to fit 160x160px container.
width
number
Width of the full-sized gallery image in px.
height
number
Height of the full-sized gallery image in px.
orderBy
number
Consecutive number of an image in the gallery.
Starts with 0 for the first image, then iterates by 1.
borderInfo
Details about image border added at the storefront.
borderInfo
dominatingColor
Border color in RGBa format.
homogeneity
boolean
Defines if an image is homogeneous.
dominatingColor
red
number
Red channel (from 0 to 255, RGB).
green
number
Green channel (from 0 to 255, RGB).
blue
number
Blue channel (from 0 to 255, RGB).
alpha
number
Alpha channel (from 0 to 255).
media
images
Details about product images.
videos
Details about product videos.
images
id
string
Internal image ID in a string format. Starts with "0" and interates by 1.
alt
Image description for the "alt" HTML attribute and its translations.
orderBy
number
Consecutive number of an image in the gallery.
Do not use for sorting. Use galleryImages[] > orderBy instead.
isMain
boolean
Defines the main product image (if true).
image160pxUrl
string
Link to the product image resized to fit 160x160px.
image400pxUrl
string
Link to the product image resized to fit 400x400px.
image800pxUrl
string
Link to the product image resized to fit 800x800px
image1500pxUrl
string
Link to the product image resized to fit 1500x1500px
imageOriginalUrl
string
Link to the full-sized product image.
externalId
string
Image ID for Lightspeed R-Series/X-Series image sync. Read-only
alt
main
string
Image description for the "alt" HTML attribute of the image.
translations
Available translations for the "alt" text.
videos
id
number
Internal video ID. Starts with "0" and interates by 1.
videoCoverId
number
Internal ID of the video cover image.
url
boolean
Link to the video file.
embedHtml
string
Video embedding code in HTML.
providerName
string
Video hosting provider name.
title
string
Video title.
image160pxUrl
string
Link to the video cover image resized to fit 160x160px container.
image400pxUrl
string
Link to the video cover image resized to fit 400x400px container.
image800pxUrl
string
Link to the video cover image resized to fit 800x800px container.
image1500pxUrl
string
Link to the video cover image resized to fit 1500x1500px container.
imageOriginalUrl
string
Link to the full-sized video cover image.
categories
id
number
Internal category ID.
name
string
Category name.
nameTranslated
Available translations for the category name.
enabled
boolean
Defines if the category is enabled.
attributes
id
number
Internal attribute ID.
name
string
Attribute name visible on the storefront.
nameTranslated
Available translations for the attribute name.
value
string
Value of the attribute for this product.
valueTranslated
Available translations for the attribute value.
type
string
Attribute type. There are user-defined attributes, general attributes and attributes pre-defined by Ecwid, for example, "price per unit".
One of:
CUSTOM
UPC
BRAND
GENDER
AGE_GROUP
COLOR
SIZE
PRICE_PER_UNIT
UNITS_IN_PRODUCT
show
string
Defines if an attribute is visible on a product page.
One of:
NOTSHOW - Not visible.
DESCR - Visible under the product description.
PRICE - Visible under the product price
files
id
number
Internal ID of the file attached to the product.
name
string
File name visible to clients.
description
string
File description visible to clients.
size
number
File size in bytes (64-bit integer).
adminUrl
string
Direct link to the file.
Important: to download the file, add your API access token to this URL like this: https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215102?token=YOUR-API-TOKEN
Do not share links containing access tokens.
relatedProducts
productIds
array of numbers
List of related product IDs.
relatedCategory
Describes the "N random related products from a category" option.
relatedCategory
enabled
boolean
Defines if the "N random related products from a category" option is enabled.
categoryId
number
ID of the related category. Empty value means that related products can be from any category.
productCount
number
Number of random products from the given category.
combinations
id
number
Internal ID for the product variation.
combinationNumber
number
Ordered variation number displayed in Ecwid admin.
Starts with 1 and iterates by 1.
options
Set of selected product option values that identify this variation.
sku
string
Variation SKU. If empty, variation inherits the base product's SKU.
thumbnailUrl
string
Link to the variation image resized to fit 400x400px container.
imageUrl
string
Link to the variation image resized to fit 1200x1200px container.
smallThumbnailUrl
string
Link to the variation image resized to fit 160x160px container.
hdThumbnailUrl
string
Link to the variation image resized to fit 800x800px container.
originalImageUrl
string
Link to the full-sized variation image.
instock
boolean
Defines if the variation is in stock (quantity is more than 0).
quantity
number
Number of variation items in stock.
If the variation has unlimited stock (unlimited is true), this field is not returned.
unlimited
boolean
Defines if the variation has unlimited stock.
price
number
Base variation price without any modifiers.
defaultDisplayedPrice
number
Variation price as it's shown on the storefront for logged out customers with default location (store location).
Pre-selected product options or variations modify the price.
Includes taxes
defaultDisplayedPriceFormatted
string
Formatted variant (curency symbol and delimeter settings) of defaultDisplayedPrice based on the store's format settings.
For example, €11,00
lowestPrice
number
Variation's lowest price for EU store.
lowestPriceSettings
Variation's lowest price settings contain only one field: lowestPriceEnabled
It defines if the lowest price is enabled for the variation.
defaultDisplayedLowestPrice
number
Variation lowest price as it's shown on the storefront for logged out customers with default location (store location). Includes taxes
defaultDisplayedLowestPriceFormatted
string
Formatted variant (curency symbol and delimeter settings) of defaultDisplayedLowestPrice based on the store's format settings.
For example, €11,00
dimensions
Variation's dimensions.
wholesalePrices
Sorted list of wholesale price tiers specific to the variation: "minimum quantity = price" pairs.
weight
number
Variation's weight for calculating shipping costs.
volume
number
Variation volume for calculations shipping costs, fractional number, 0 by default.
warningLimit
number
Minimum amount of variation in stock to trigger an automated "low stock" email notification for the store owner.
attributes
List of variation attributes and their values.
compareToPrice
number
Pre-sale price for the variation.
minPurchaseQuantity
number
Sets minimum product purchase quantity.
Default value is null.
maxPurchaseQuantity
number
Sets maximum product purchase quantity.
Default value is null.
outOfStockVisibilityBehaviour
boolean
Defines if a variation is visible and/or can be pre-ordered when out-of-stock.
Requires enabled pre-orders on the store level: allowPreordersForOutOfStockProducts setting in /profile endpoint.
Supported values:
SHOW - Show out-of-stock variation, but adding it to the cart is disabled.
ALLOW_PREORDER - Show out-of-stock variation and allow adding it to the cart.
alt
Variation image description for the "alt" HTML attribute and its translations.
options (variation)
name
string
Name of the selected option.
nameTranslated
Available translations for the product option name.
value
string
Value of the selected option.
valueTranslated
Available translations for the product option value.
dimensions
length
number
Length of a product for calculating shipping costs.
width
number
Width of a product for calculating shipping costs.
height
number
Height of a product for calculating shipping costs.
subscriptionSettings
Internal details on product subscriptions.
subscriptionAllowed
boolean
true if the product can be sold as subscription ("Sell as subscription" product setting enabled). false otherwise.
oneTimePurchaseAllowed
boolean
true if the product can be purchased once, with no further charges on a regular basis. false otherwise.
oneTimePurchasePrice
number
The cost of the product by subscription with a one-time purchase, null by default.
oneTimePurchasePriceFormatted
string
The cost of the product for a one-time purchase, formatted according to the settings for displaying prices in the store.
oneTimePurchaseMarkup
number
The difference between the price of the product when subscribing and a one-time purchase in absolute values. Calculated automatically when oneTimePurchasePrice that isn’t equal to price is set.
oneTimePurchaseMarkupFormatted
string
The difference between the price of the product when subscribing and a one-time purchase in absolute values. Formatted according to the settings for displaying prices in the store. Updated automatically when the oneTimePurchaseMarkup is changed.
oneTimePurchaseMarkupPercent
number
The difference between the price of the product when subscribing and a one-time purchase as a percentage. Calculated automatically when oneTimePurchasePrice that isn’t equal to price is set.
oneTimePurchaseMarkupPercentFormatted
string
The difference between the price of the product when subscribing and a one-time purchase as a percentage. Formatted according to the settings for displaying prices in the store. Updated automatically when the oneTimePurchaseMarkupPercent is changed.
recurringChargeSettings
Recurring charge settings.
recurringChargeSettings
Internal details on recurring charges for product subscriptions.
recurringInterval
string
Charge recurring interval. Supported values: DAY, WEEK, MONTH, YEAR.
recurringIntervalCount
number
Charge recurring interval. Supported values: for DAY - 1 (daily), for WEEK - 1 (weekly), 2 (biweekly), for MONTH - 1 (monthly), 3 (quarterly), for YEAR - 1 (annually).
subscriptionPriceWithSignUpFee
number
The cost of the product for the first subscription order.
subscriptionPriceWithSignUpFeeFormatted
string
The cost of the product for the first subscription order. Formatted according to the settings for displaying prices in the store. Updated automatically when the subscriptionPriceWithSignUpFee is changed.
signUpFee
number
The size of the markup that is imposed on the first order.
signUpFeeFormatted
string
The size of the markup that is imposed on the first order. Formatted according to the settings for displaying prices in the store. Updated automatically when the signUpFee is changed.
tax
taxable
boolean
Defines if taxes can be applied to the product.
defaultLocationIncludedTaxRate
number
Default tax rate (%) for including into product price. It's a sum of all enabled taxes included in product price for the store location. Read only
enabledManualTaxes
array of numbers
List of internal IDs for manual taxes. Empty if no manual taxes are enabled or automatic taxes are enabled.
taxClassCode
string
Tax class code for the product that determines the taxability of the products for a certain region.
translations
Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. For example:
Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with GET /profile request > languages > enabledLanguages.
Last updated
Was this helpful?