# Search products
`GET` `https://app.ecwid.com/api/v3/{storeId}/products`
Request and response example
Request:
```http
GET /api/v3/1003/products HTTP/1.1
Authorization: Bearer secret_token
Host: app.ecwid.com
```
Response:
```json
{
"total": 2,
"count": 2,
"offset": 0,
"limit": 100,
"items": [
{
"id": 692730761,
"sku": "123123",
"thumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591923.jpg",
"unlimited": true,
"inStock": true,
"name": "Toys",
"nameTranslated": {
"cs": "",
"en": "Toys"
},
"price": 10,
"priceInProductList": 10,
"defaultDisplayedPrice": 10,
"defaultDisplayedPriceFormatted": "€10,00",
"tax": {
"taxable": true,
"defaultLocationIncludedTaxRate": 10,
"enabledManualTaxes": [
947976181
],
"taxClassCode": "default"
},
"lowestPrice": 10,
"defaultDisplayedLowestPrice": 10,
"defaultDisplayedLowestPriceFormatted": "€10,00",
"lowestPriceSettings": {
"lowestPriceEnabled": true
},
"isShippingRequired": false,
"hasFreeShipping": false,
"url": "https://store1003.company.site/products/toys",
"autogeneratedSlug": "toys-692730761",
"customSlug": "",
"created": "2024-09-04 07:20:11 +0000",
"updated": "2024-09-04 07:20:12 +0000",
"createTimestamp": 1725434411,
"updateTimestamp": 1725434412,
"productClassId": 0,
"enabled": true,
"options": [],
"warningLimit": 1,
"fixedShippingRateOnly": false,
"fixedShippingRate": 0,
"shipping": {
"type": "GLOBAL_METHODS",
"methodMarkup": 0,
"flatRate": 0,
"disabledMethods": [],
"enabledMethods": []
},
"defaultCombinationId": 0,
"imageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591921.jpg",
"smallThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591920.jpg",
"hdThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591922.jpg",
"originalImageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591919.jpg",
"originalImage": {
"url": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591919.jpg",
"width": 225,
"height": 225
},
"borderInfo": {
"dominatingColor": {
"red": 255,
"green": 255,
"blue": 255,
"alpha": 255
},
"homogeneity": true
},
"description": "",
"descriptionTranslated": {
"cs": "",
"en": ""
},
"galleryImages": [],
"media": {
"images": [
{
"id": "0",
"isMain": true,
"orderBy": 0,
"image160pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591920.jpg",
"image400pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591923.jpg",
"image800pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591922.jpg",
"image1500pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591921.jpg",
"imageOriginalUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4519591919.jpg",
"alt": {
"translated": {}
}
}
],
"videos": []
},
"categoryIds": [],
"categories": [],
"defaultCategoryId": 0,
"seoTitle": "Toys",
"seoTitleTranslated": {
"cs": "",
"en": "Toys"
},
"seoDescription": "",
"seoDescriptionTranslated": {
"cs": "",
"en": ""
},
"favorites": {
"count": 0,
"displayedCount": "0"
},
"attributes": [],
"files": [
{
"id": 96178524,
"name": "image.jpeg",
"description": "",
"size": 12006,
"adminUrl": "https://app.ecwid.com/api/v3/1003/products/692730761/files/96178524"
}
],
"relatedProducts": {
"productIds": [],
"relatedCategory": {
"enabled": false,
"categoryId": 0,
"productCount": 5
}
},
"combinations": [],
"dimensions": {
"length": 0,
"width": 0,
"height": 0
},
"shippingPreparationTime": {},
"showDeliveryTimeInStorefront": false,
"volume": 0,
"showOnFrontpage": 11,
"isSampleProduct": false,
"googleItemCondition": "NEW",
"isGiftCard": false,
"discountsAllowed": true,
"nameYourPriceEnabled": false,
"subscriptionSettings": {
"subscriptionAllowed": false,
"oneTimePurchaseAllowed": true,
"recurringChargeSettings": [
{
"recurringInterval": "MONTH",
"recurringIntervalCount": 1
}
]
},
"googleProductCategory": 412,
"googleProductCategoryName": "Food, Beverages & Tobacco",
"productCondition": "NEW",
"outOfStockVisibilityBehaviour": "SHOW"
},
{
"id": 689454040,
"sku": "00001",
"thumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679704.jpg",
"unlimited": true,
"inStock": true,
"name": "Best Pizza",
"nameTranslated": {
"cs": "",
"en": "Best Pizza"
},
"price": 50,
"priceInProductList": 50,
"defaultDisplayedPrice": 50,
"defaultDisplayedPriceFormatted": "€50,00",
"tax": {
"taxable": true,
"defaultLocationIncludedTaxRate": 10,
"enabledManualTaxes": [
947976181
],
"taxClassCode": "default"
},
"lowestPrice": 50,
"defaultDisplayedLowestPrice": 50,
"defaultDisplayedLowestPriceFormatted": "€50,00",
"lowestPriceSettings": {
"lowestPriceEnabled": true
},
"compareToPrice": 40,
"compareToPriceFormatted": "€40,00",
"compareToPriceDiscount": -10,
"compareToPriceDiscountFormatted": "€-10,00",
"compareToPriceDiscountPercent": -25,
"compareToPriceDiscountPercentFormatted": "",
"defaultDisplayedCompareToPrice": 40,
"defaultDisplayedCompareToPriceFormatted": "€40,00",
"defaultDisplayedCompareToPriceDiscount": -10,
"defaultDisplayedCompareToPriceDiscountFormatted": "€-10,00",
"defaultDisplayedCompareToPriceDiscountPercent": -25,
"defaultDisplayedCompareToPriceDiscountPercentFormatted": "",
"isShippingRequired": true,
"hasFreeShipping": false,
"weight": 0.5,
"url": "https://store1003.company.site/products/pizza",
"autogeneratedSlug": "pizza-689454040",
"customSlug": "pizza",
"created": "2024-08-19 08:49:01 +0000",
"updated": "2024-09-05 07:58:07 +0000",
"createTimestamp": 1724057341,
"updateTimestamp": 1725523087,
"productClassId": 0,
"enabled": true,
"options": [
{
"type": "RADIO",
"name": "Size",
"nameTranslated": {
"cs": "",
"en": "Size"
},
"choices": [
{
"text": "24",
"textTranslated": {
"cs": "",
"en": "24"
},
"priceModifier": 0,
"priceModifierType": "ABSOLUTE"
},
{
"text": "28",
"textTranslated": {
"cs": "",
"en": "28"
},
"priceModifier": 10,
"priceModifierType": "ABSOLUTE"
},
{
"text": "32",
"textTranslated": {
"cs": "",
"en": "32"
},
"priceModifier": 20,
"priceModifierType": "ABSOLUTE"
}
],
"required": true
}
],
"warningLimit": 1,
"fixedShippingRateOnly": false,
"fixedShippingRate": 0,
"shipping": {
"type": "GLOBAL_METHODS",
"methodMarkup": 0,
"flatRate": 0,
"disabledMethods": [],
"enabledMethods": []
},
"defaultCombinationId": 0,
"imageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679702.jpg",
"smallThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679701.jpg",
"hdThumbnailUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679703.jpg",
"originalImageUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679700.jpg",
"originalImage": {
"url": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679700.jpg",
"width": 683,
"height": 512
},
"borderInfo": {
"dominatingColor": {
"red": 129,
"green": 96,
"blue": 73,
"alpha": 255
},
"homogeneity": false
},
"description": "",
"descriptionTranslated": {
"cs": "",
"en": ""
},
"galleryImages": [],
"media": {
"images": [
{
"id": "0",
"isMain": true,
"orderBy": 0,
"image160pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679701.jpg",
"image400pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679704.jpg",
"image800pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679703.jpg",
"image1500pxUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679702.jpg",
"imageOriginalUrl": "https://d2j6dbq0eux0bg.cloudfront.net/images/1003/4493679700.jpg",
"alt": {
"main": "alt_tag",
"translated": {
"en": "alt_tag",
"cz": "alt_tag_cz"
}
}
}
],
"videos": []
},
"categoryIds": [],
"categories": [],
"defaultCategoryId": 0,
"seoTitle": "Best Pizza",
"seoTitleTranslated": {
"cs": "",
"en": "Best Pizza"
},
"seoDescription": "",
"seoDescriptionTranslated": {
"cs": "",
"en": ""
},
"favorites": {
"count": 0,
"displayedCount": "0"
},
"attributes": [],
"files": [],
"relatedProducts": {
"productIds": [],
"relatedCategory": {
"enabled": false,
"categoryId": 0,
"productCount": 5
}
},
"combinations": [
{
"id": 421616046,
"combinationNumber": 2,
"options": [
{
"name": "Size",
"nameTranslated": {
"cs": "",
"en": "Size"
},
"value": "32",
"valueTranslated": {
"cs": "",
"en": "32"
}
}
],
"inStock": true,
"unlimited": true,
"attributes": [],
"defaultDisplayedPrice": 70,
"defaultDisplayedPriceFormatted": "€70,00",
"dimensions": {
"length": 0,
"width": 0,
"height": 0
},
"volume": 0,
"outOfStockVisibilityBehaviour": "SHOW",
"lowestPrice": 50,
"defaultDisplayedLowestPrice": 50,
"defaultDisplayedLowestPriceFormatted": "€50,00",
"lowestPriceSettings": {
"lowestPriceEnabled": true
},
"alt": {
"main": "alt_tag",
"translated": {
"cz": "alt_tag_cz",
"en": "alt_tag"
}
}
},
{
"id": 421616047,
"combinationNumber": 1,
"options": [
{
"name": "Size",
"nameTranslated": {
"cs": "",
"en": "Size"
},
"value": "28",
"valueTranslated": {
"cs": "",
"en": "28"
}
}
],
"inStock": true,
"unlimited": true,
"attributes": [],
"defaultDisplayedPrice": 60,
"defaultDisplayedPriceFormatted": "€60,00",
"dimensions": {
"length": 0,
"width": 0,
"height": 0
},
"volume": 0,
"outOfStockVisibilityBehaviour": "SHOW",
"lowestPrice": 50,
"defaultDisplayedLowestPrice": 50,
"defaultDisplayedLowestPriceFormatted": "€50,00",
"lowestPriceSettings": {
"lowestPriceEnabled": true
},
"alt": {
"main": "alt_tag",
"translated": {
"cz": "alt_tag_cz",
"en": "alt_tag"
}
}
}
],
"dimensions": {
"length": 0,
"width": 0,
"height": 0
},
"shippingPreparationTime": {},
"showDeliveryTimeInStorefront": false,
"volume": 0,
"showOnFrontpage": 10,
"isSampleProduct": false,
"googleItemCondition": "NEW",
"isGiftCard": false,
"discountsAllowed": true,
"nameYourPriceEnabled": false,
"subscriptionSettings": {
"subscriptionAllowed": false,
"oneTimePurchaseAllowed": true,
"recurringChargeSettings": [
{
"recurringInterval": "MONTH",
"recurringIntervalCount": 1
}
]
},
"googleProductCategory": 412,
"googleProductCategoryName": "Food, Beverages & Tobacco",
"productCondition": "NEW",
"outOfStockVisibilityBehaviour": "SHOW"
}
]
}
```
### Required access scopes
Your app must have the following **access scopes** to make this request: `read_catalog`
### Path params
All path params are required.
| Param | Type | Description |
| ------- | ------ | --------------- |
| storeId | number | Ecwid store ID. |
### Query params
All query params are optional.
| Param | Type | Description |
|---|
| 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)optionscategory namegallery image descriptionsattributes values (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). |
| enabledManualTaxes | string | ID of an enabled manual tax. Supports multiple values, for example, 1117939042,4892697021 and the none value to search for the products with no enabled taxes.
For example, you can filter products with no enabled taxes or a manual tax with a query param like ?enabledManualTaxes=none,1117939042. |
| taxClassCodes | string | List of tax class codes. Find tax classes and their codes in the dictionary. |
| 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:
{% tabs %}
{% tab title="Request" %}
```
curl --location 'https://app.ecwid.com/api/v3/1003/orders?responseFields=total,items(id,email,total)' \
--header 'Authorization: Bearer secret_ab***cd'
```
{% endtab %}
{% tab title="Response" %}
```
{
"total": 2,
"items": [
{
"id": 692730761,
"name": "Toys",
"price": 10
},
{
"id": 689454040,
"name": "Best Pizza",
"price": 50
}
]
}
```
{% endtab %}
{% endtabs %}
### Headers
The **Authorization** header is required.
| Header | Format | Description |
|---|
| Authorization | Bearer secret_ab***cd | Access token of the application. |
### Response JSON
A JSON object with the following fields:
| Field | Type | Description |
| ------ | -------------------------------- | -------------------------------------------------------------------------------------------- |
| 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 | array of objects [items](#items) | Detailed information about returned products. |
#### items
| Field | Type | Description |
| ------------------------------------------------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 | object [#translations](#translations "mention") | 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 | array of objects [wholesalePrices](#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 | object [lowestPriceSettings](#lowestpricesettings) | Product lowest price settings for EU stores.
Read more on lowes price settings in Help Center.
|
| 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 | ID of the product class that affects attributes management.
If it's 0 the product belongs to the default "General" class.
Read more on product types and attributes in Help Center.
|
| 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 | array of objects [options](#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 | object [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 | object [originalImage](#originalimage) | Details about product main image. |
| galleryImages | object [galleryImages](#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 | object [translations](#translations) | Available translations for the product description. |
| media | object [media](#media) | Details about product images and videos. |
| categoryIds | array of numbers | List of the category IDs the product belongs to. |
| categories | array [categories](#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 | object [translations](#translations) | Translations for the SEO page title. |
| seoDescription | string | Page description for search engines.
Recommended length < 160 characters.
|
| seoDescriptionTranslated | object [translations](#translations) | Translations for the SEO page description. |
| favorites | object [favorites](#favorites) | Stats showing how many times the product was added to favorites on the storefront. |
| attributes | array of objects [attributes](#attributes) | List of product attributes and their values. |
| files | array of objects [files](#files) | Details about downloadable files attached to the product. |
| relatedProducts | object [relatedProducts](#relatedproducts) | List of related products displayed as "You may also like" products of the product. |
| combinations | array of objects [combinations](#combinations) | Details about product variations. |
| dimensions | object [dimensions](#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 | object [subscriptionSettings](#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 | object [translations](#translations) | 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.
This ID is unique for each product in one store.
|
| 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. |
| compositeParents | array of numbers | List of composite product IDs that this product is a component of. |
| compositeComponents | array of objects [compositeComponents](#compositecomponents) | List of products/variations that turn this product into a "composite product". |
#### favorites
| Field | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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
| Field | Type | Description |
|---|
| quantity | number | Number of product items on this wholesale tier. |
| price | number | Product price on the tier. |
#### lowestPriceSettings
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| type | string | Option type that defines its functionality.
One of: SELECT - Drop-down list with several options. Users can select only one of the options provided.
RADIO - Radio buttons. Users can select only one of the options provided.
CHECKBOX - Checkbox options. Users can select several options at the same time.
TEXTFIELD - Single-line text input field.
TEXTAREA - Multi-lines text input field.
DATE - Date and time selector.
FILES - File uploader for users.
SIZE - Selector for the product sizes. Works the same way as radio buttons.
SWATCHES - Selector for the product colors. Works the same way as radio buttons.
|
| name | string | Product option name. For example: Color or Size. |
| nameTranslated | object translations | Available translations for product option name. |
| choices | array of objects choices | List of available option choices for users.
Only works for the following option types: SELECT, CHECKBOX, RADIO, SIZE, or SWATCHES. |
| defaultChoice | number | Index of the option's default selection. Can be null (no default option), otherwise starts with 0.
Only works for the following option types: SELECT, CHECKBOX, RADIO, SIZE, or SWATCHES. |
| required | boolean | Defines if this option is required to add product to the cart. |
| useImageAsSwatchSelector | boolean | Display mode for the color swatches option. Only works with SWATCHES option type. One of: true - show specific product images when a user choses different color at the storefront.false - show color swatches defines as hex codes when user chooses different color at the storefront.
|
#### choices
| Field | Type | Description |
|---|
| text | string | Text displayed near the option choise or as it at the storefront. For example, a text near the radio button or a checkbox, choice name in the dropdown list, etc. |
| textTranslated | object translations | Available translations for choice's text field. |
| priceModifier | number | Value of the option's price markup.
Positive, negative (in case the option reduces the pice) and zero values are allowed. Default is 0 |
| priceModifierType | string | Option markup calculation type.
One of: PERCENT - price modifier applied as a percent increase to the product price.
ABSOLUTE - price modifier applied as an absolute increase to the product price (default).
|
| hexCodes | array of strings | List of HEX codes. Defines what color must be displayed when user changes color in the SWATCHES option, for example: ["#fff000"].
Requires useImageAsSwatchSelector to be true. |
| changeTime | number | UNIX timestamp of the latest change in the product option. |
| imageId | string | Internal ID of the product image.
Defines what product image must be displayed when user changes color in the SWATCHES option.
Requires useImageAsSwatchSelector to be true. |
#### shipping
| Field | Type | Description |
|---|
| 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 | IDs of shipping methods that need to be excluded from calculation when this product is in cart.
Full list of shipping method IDs is available thorugh the Store profile call. |
| enabledMethods | array of strings | IDs of shipping methods which will only be shown when this product is in cart. No other shipping methods will be shown.
Full list of shipping method IDs is available thorugh the Store profile call. |
#### originalImage
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
|---|
| 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 | object borderInfo | Details about image border added at the storefront. |
#### borderInfo
| Field | Type | Description |
| --------------- | ------------------------------------------ | ----------------------------------- |
| dominatingColor | object [dominatingColor](#dominatingcolor) | Border color in RGBa format. |
| homogeneity | boolean | Defines if an image is homogeneous. |
#### dominatingColor
| Field | Type | Description |
|---|
| 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
| Field | Type | Description |
| ------ | ---------------------------------- | ----------------------------- |
| images | array of objects [images](#images) | Details about product images. |
| videos | array of objects [videos](#videos) | Details about product videos. |
#### images
| Field | Type | Description |
|---|
| id | string | Internal image ID in a string format. Starts with "0" and interates by 1. |
| alt | object 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
| Field | Type | Description |
|---|
| main | string | Image description for the "alt" HTML attribute of the image. |
| translations | object translations | Available translations for the "alt" text. |
#### videos
| Field | Type | Description |
|---|
| 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. |
#### compositeComponents
| Field | Type | Description |
| ------------- | ------ | ----------------------------------------------------------------------- |
| productId | number | ID of the product in this composite product. |
| combinationId | number | ID of the product variation in this composite product. |
| quantity | number | Quantity of the product or product variation in this composite product. |
#### categories
| Field | Type | Description |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| id | number | Internal category ID. |
| name | string | Category name. |
| nameTranslated | string | Translated category name. Uses first non-default store language if possible. Otherwise, copies category name in the default store language. |
| enabled | boolean | Defines if the category is enabled. |
#### attributes
| Field | Type | Description |
|---|
| id | number | Internal attribute ID. |
| name | string | Attribute name visible on the storefront. |
| nameTranslated | object translations | Available translations for the attribute name. |
| value | string | Value of the attribute for this product. |
| valueTranslated | object translations | 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
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:
Do not share links containing access tokens.
|
#### relatedProducts
| Field | Type | Description |
| --------------- | ------------------------------------------ | ----------------------------------------------------------------- |
| productIds | array of numbers | List of related product IDs. |
| relatedCategory | object [relatedCategory](#relatedcategory) | Describes the "N random related products from a category" option. |
#### relatedCategory
| Field | Type | Description |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| 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
| Field | Type | Description |
| ------------------------------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 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 | array of objects [options (variation)](#options-variation) | 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 | object [lowestPriceSettings](#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 | object [dimensions](#dimensions) | Variation's dimensions. |
| wholesalePrices | array of objects [wholesalePrices](#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 | array of objects [attributes](#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 | object [alt](#alt) | Variation image description for the "alt" HTML attribute and its translations. |
#### options (variation)
| Field | Type | Description |
| --------------- | ------------------------------------ | ---------------------------------------------------- |
| name | string | Name of the selected option. |
| nameTranslated | object [translations](#translations) | Available translations for the product option name. |
| value | string | Value of the selected option. |
| valueTranslated | object [translations](#translations) | Available translations for the product option value. |
#### dimensions
| Field | Type | Description |
|---|
| 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.
| Field | Type | Description |
| ------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 | object [recurringChargeSettings](#recurringchargesettings) | Recurring charge settings. |
#### recurringChargeSettings
Internal details on recurring charges for product subscriptions.
| Field | Type | Description |
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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
| Field | Type | Description |
| ------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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:
```
{
"en": "Sample text",
"nl": "Voorbeeldtekst"
}
```
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`.