Get all details of a specific product in an Ecwid store by its ID.
Headers
Name | Type | Description |
---|---|---|
Authorization | string | oAuth token with mandatory Bearer before it. Example: Bearer e***s0 , where e***s0 should be replaced with your oAuth token. |
Q: How can I request details of several products at once?
If you need to do this operation for multiple products at once (batch request), you can use the Search products method: provide the productIds you have in the productId
parameter separating them with a comma.
This way your app will save some time as you will be performing less requests to the Ecwid API and they will be much more efficient.
Query parameters
Field | Type | Description |
---|---|---|
baseUrl | string | Storefront URL for Ecwid to use when returning product URLs in the url field. If not specified, Ecwid will use the storefront URL specified in the store settings |
cleanUrls | boolean | If true , Ecwid will return the SEO-friendly clean URL (without hash '#' ) in the url field. If false , Ecwid will return URL in the old format (with hash '#' ). We recommend using true value if merchant's website supports clean SEO-friendly URL feature |
lang | string | Preferred language for the product fields in search results. If a certain field does not have the translation available for the set language, the default language text will be used for that field. |
Response
A JSON object of type 'Product' with the following fields:
Product
Field | Type | Description |
---|---|---|
id | number | Unique integer product identifier |
sku | string | Product SKU. Items with options can have several SKUs specified in the product variations |
quantity | number | Amount of product items in stock. This field is omitted for the products with unlimited stock |
locationInventory | <LocationInventory> | Relates to X-series integration. Contains stock data distributed by X-series location ID (string, number). |
unlimited | boolean | true if the product has unlimited stock |
inStock | boolean | true if the product or any of its variations is in stock (quantity is more than zero) or has unlimited quantity. false otherwise. |
name | string | Product title |
nameTranslated | <Translations> | Available translations for product name |
price | number | Base product price |
defaultDisplayedPrice | number | Product price displayed in a storefront for logged out customer for default location (store location). May differ from the price value when the product has options and variations and the default variation's price is different from the base product price. It also includes taxes |
defaultDisplayedPriceFormatted | string | Formatted display of defaultDisplayedPrice in the store's formatting for prices |
costPrice | number | Purchase price (the price at which the seller bought the product from the supplier). A positive number, 0 by default. The field is not shown in the UI and can be used for reports and profit calculations |
tax | <TaxInfo> | Detailed information about product's taxes |
wholesalePrices | Array<WholesalePrice> | Sorted array of wholesale price tiers (quantity limit and price pairs) |
compareToPrice | number | Product's sale price displayed strike-out in the customer frontend Omitted if empty |
compareToPriceFormatted | string | Formatted display of compareToPrice in the store's formatting for prices |
compareToPriceDiscount | number | Sale price discount amount |
compareToPriceDiscountFormatted | string | Sale price formatted discount amount (with store currency) |
compareToPriceDiscountPercent | number | Sale price discount percent |
compareToPriceDiscountPercentFormatted | string | Sale price discount percent (with percent sign) |
isShippingRequired | boolean | true if product requires shipping, false otherwise |
weight | number | Product weight in the units defined in store settings. Omitted for intangible products |
url | string | URL of product details page in the storefront. URL will be provided in SEO-friendly format if Ecwid knows the store uses them. |
created | string | Date and time of the product creation. Example: 2014-07-30 10:32:37 +0000 |
updated | string | Product last update date/time |
createTimestamp | number | The date of product creation in UNIX Timestamp format, e.g 1427268654 |
updateTimestamp | number | Product last update date in UNIX Timestamp format, e.g 1427268654 |
productClassId | number | Id of the class (type) that this product belongs to. 0 value means the product is of the default 'General' class. See also: Product types and attributes in Ecwid |
enabled | boolean | true if product is enabled, false otherwise. Disabled products are not displayed in the store front. |
options | Array<ProductOption> | A list of the product options. Empty ([] ) if no options are specified for the product. |
warningLimit | number | The minimum 'warning' amount of the product items in stock, if set. When the product quantity reaches this level, the store administrator gets an email notification. |
fixedShippingRateOnly | boolean | Legacy function – see shipping field instead. Is ignored if it is sent alongside shipping object. 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 function – see shipping field instead. Is ignored if it is sent alongside shipping object. 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 | <ShippingSettings> | Shipping settings of this product |
defaultCombinationId | number | Identifier of the default product variation, which is defined by the default values of product options. |
originalImage | Array<OriginalImage> | Original image information |
description | string | Product description in HTML |
descriptionTranslated | <Translations> | Available translations for product description |
galleryImages | Array<GalleryImages> | List of the product gallery images (for updating alt tags and sort order) |
media | <ProductMedia> | Media files for a product (images) |
categoryIds | Array<number> | Private token: List of the categories, which the product belongs to. Public token: List of the enabled categories the product belongs to. Any access token: If no categories provided, product is displayed on the store front page, see showOnFrontpage field, or all categories of that product are disabled |
categories | Array<CategoriesInfo> | List of the categories the product belongs to with brief details (for any access token). If no categories provided, product belogs to store front page, see showOnFrontpage field |
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 to be displayed in search results on the web. Recommended length is under 55 characters. Is empty if value wasn't changed by merchant from the product itself |
seoTitleTranslated | string | Translations of the page title to be displayed in search results on the web |
seoDescription | string | Page description to be displayed in search results on the web. Recommended length is under 160 characters. Is empty if value wasn't changed by merchant from the product itself |
seoDecriptionTranslated | string | Translations of the page description to be displayed in search results on the web |
favorites | <FavoritesStats> | Product favorites stats |
attributes | Array<AttributeValue> | Product attributes and their values |
files | Array<ProductFile> | Downloadable files (E-goods) attached to the product |
relatedProducts | <RelatedProducts> | Related or "You may also like" products of the product |
combinations | Array<Variation> | List of the product variations |
dimensions | <ProductDimensions> | Product dimensions info |
volume | number | Product volume, fractional number, 0 by default. |
showOnFrontpage | number | A positive number indicates the position (index) of a product in the store front page – the smaller the number, the higher the product is displayed on a page. A missing field means the product is not shown in the store front page (for private tokens) |
isSampleProduct | boolean | true if this product is a sample one (sample product when Ecwid store is initially created). false otherwise. Read only field |
isGiftCard | boolean | true if a product is a gift card. false if it's a regular store product. Read only field |
discountsAllowed | boolean | true if Ecwid can apply discounts to this product at checkout. false otherwise |
nameYourPriceEnabled | boolean | true if the "Pay What You Want " feature is enabled. false otherwise. |
subscriptionSettings | <SubscriptionSettings> | Subscription settings |
subtitle | text | Short product description for categories or search pages. |
ribbon | <Ribbon> | Small product label visible on categories and product pages. |
subtitleTranslated | <Translations> | Available translations for product subtitles. |
ribbonTranslated | <Translations> | Available translations for product ribbons. |
externalReferenceId | string | External ID for products synced from external services (e.g. POS) |
customsHsTariffCode | string | Product code for customs reference. Omitted if empty |
outOfStockVisibilityBehaviour | string | Indicates whether an out of stock product should visible or not. One of: SHOW , HIDE , ALLOW_PREORDER . |
minPurchaseQuantity | number | Sets minimum product purchase quantity. null by default. Not visible if the value is not assigned. |
maxPurchaseQuantity | number | Sets maximum product purchase quantity. null by default. Not visible if the value is not assigned. |
LocationInventory
Field | Type | Description |
---|---|---|
<X-seriese_location_ID> | number | The actual amount of product items in the location's stock |
FavoritesStats
Field | Type | Description |
---|---|---|
count | number | The actual number of 'likes' of this product |
displayedCount | string | The displayed number of likes. May differ from the count if, for example, the value is more than 1000, than it will show 1K instead of the precise number |
WholesalePrice
Field | Type | Description |
---|---|---|
quantity | number | Number of product items on this wholesale tier |
price | number | Product price on the tier |
ProductOption
Field | Type | Description |
---|---|---|
type | string | One of SELECT , RADIO , CHECKBOX , TEXTFIELD , TEXTAREA , DATE , FILES , SIZE |
name | string | Product option name, e.g. Color |
nameTranslated | <Translations> | Available translations for product option name |
choices | Array<ProductOptionChoice> | All possible option selections for the types SELECT , CHECKBOX or RADIO or SIZE . This field is omitted for the product option with no selection (e.g. text, datepicker or upload file options) |
defaultChoice | number | The number, starting from 0 , of the option's default selection. Only presents if the type is SELECT or RADIO or SIZE |
required | boolean | true if this option is required (defaultChoice is ignored in that case, customer has to choose an option himself), false otherwise. Default is false . The Do not preselect default value checkbox in Control Panel has the same effect. |
ShippingSettings
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 cost for shipping methods set by merchant (global and selected) |
flatRate | number | Flat rate cost for shipping this product |
disabledMethods | Array of string | IDs of shipping methods that need to be excluded from calculation when this product is in cart. IDs can be retrieved in Store profile |
enabledMethods | Array of string | IDs of shipping methods which will only be shown when this product is in cart. No other shipping methods will be shown. IDs can be retrieved in Store profile |
OriginalImage
Field | Type | Description |
---|---|---|
url | string | Url of an original image |
width | number | Width of an image (px) |
height | number | Height of an image (px) |
GalleryImages
Field | Type | Description |
---|---|---|
id | number | Id of an image in the gallery |
url | string | URL of an image |
thumbnail | string | URL of a thumbnail (160px) |
originalImageUrl | string | URL of an original image |
imageUrl | string | URL of an image (1200px) |
hdThumbnailUrl | string | URL of an HD-thumbnail (800px) |
thumbnailUrl | string | URL of a big thumbnail (400px) |
smallThumbnailUrl | string | URL of a thumbnail (160px) |
width | number | Width of an image (px) |
height | number | Height of an image (px) |
orderBy | number | Consecutive number of an image in the gallery |
borderInfo | Array<BorderInfo> | Border information |
BorderInfo
Field | Type | Description |
---|---|---|
dominatingColor | Array<DominatingColor> | Dominating color information |
homogeneity | boolean | true if an image is homogeneous. false otherwise |
DominatingColor
Field | Type | Description |
---|---|---|
red | number | Red color (from 0 to 255, RGB) |
green | number | Green color (from 0 to 255, RGB) |
blue | number | Blue color (from 0 to 255, RGB) |
alpha | number | Alpha channel (from 0 to 255) |
ProductMedia
Field | Type | Description |
---|---|---|
images | Array <ProductImage> | Images of this product and their details |
ProductImage
Field | Type | Description |
---|---|---|
id | number | Internal image ID |
orderBy | number | The sort weight of the image in the gallery images list. The less the number, the closer the image to the beginning of the gallery |
isMain | boolean | true if this is a main product image. false if gallery image |
image160pxUrl | string | URL of the product thumbnail resized to fit 160x160px |
image400pxUrl | string | URL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of the biggest dimension is 400px |
image800pxUrl | string | Product HD thumbnail URL resized to fit 800x800px |
image1500pxUrl | string | URL of the product image resized to fit 1500x1500px |
imageOriginalUrl | string | URL of the image in its original resolution |
CategoriesInfo
Field | Type | Description |
---|---|---|
id | number | Category ID |
enabled | boolean | true if category is enabled, false otherwise |
AttributeValue
Field | Type | Description |
---|---|---|
id | number | Unique attribute ID. See Product types for the information on attribute IDs |
name | string | Attribute displayed name |
nameTranslated | <Translations> | Available translations for product attribute name |
value | string | Attribute value |
valueTranslated | <Translations> | Available translations for product attribute value |
type | string | Attribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: 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. Supported values: NOTSHOW , DESCR , PRICE . The value PRICE = DESCR . |
ProductFile
Field | Type | Description |
---|---|---|
id | number | Internal ID of the file |
name | string | File name |
description | string | File description defined by the store administrator |
size | number | File size, bytes (64-bit integer) |
adminUrl | string | Direct link to the file. Important: to download the file, add your API token to this URL like this: https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215102?token=YOUR-API-TOKEN |
RelatedProducts
Field | Type | Description |
---|---|---|
productIds | Array<number> | IDs of the related products |
relatedCategory | RelatedCategory | Describes the "N random related products from a category" option |
RelatedCategory
Field | Type | Description |
---|---|---|
enabled | boolean | true if the "N random related products from a category" option is enabled. false otherwise |
categoryId | number | Id of the related category. Zero value means "any category", that is, random products from the whole store. |
productCount | number | Number of random products from the given category to be shown as related |
Variation
Field | Type | Description |
---|---|---|
id | number | Variation ID |
combinationNumber | number | Variation # number, which is displayed in the variations table in Control panel |
options | Array<OptionValue> | Set of options that identifies this variation. An array of name-value pairs |
sku | string | Variation SKU. Omitted if the variation inherits the base product's SKU |
thumbnailUrl | string | URL of the product variation thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the variation inherits the base product's image. The original uploaded product image is available in the originalImageUrl field. |
imageUrl | string | URL of the product variation image resized to fit 1500x1500px. Omitted if the variation inherits the base product's image. The original uploaded product image is available in the originalImageUrl field. |
smallThumbnailUrl | string | URL of the product variation thumbnail resized to fit 160x160px. Omitted if the variation inherits the base product's image. The original uploaded product image is available in the originalImageUrl field. |
hdThumbnailUrl | string | Product variation HD thumbnail URL resized to fit 800x800px. Omitted if the variation inherits the base product's image. |
originalImageUrl | string | URL of the original not resized product variation image. Omitted if the variation inherits the base product's image. |
quantity | number | Amount of the variation items in stock. If sku is omitted, then quantity of the variation is nested from base product. If sku is present, the variation has its own quantity value. |
unlimited | boolean | true if the variation has unlimited stock (that is, never runs out) |
price | number | Variation price. Omitted if the variation inherits the base product's price. |
wholesalePrices | Array<WholesalePrice> | Sorted array of the variation's wholesale price tiers (quantity limit and price). Omitted if the variation inherits the base product's tiered price settings. |
weight | number | Variation weight in the units defined in store settings. Omitted if the variation inherits the base product's weight. |
warningLimit | number | The minimum 'warning' amount of the product items in stock for this variation, if set. When the variation in stock amount reaches this level, the store administrator gets an email notification. Omitted if the variation inherits the base product's settings |
attributes | Array<AttributeValue> | Variation's UPC attribute and its value |
compareToPrice | number | Variation's sale price displayed strike-out in the customer frontend Omitted if empty |
minPurchaseQuantity | number | Sets minimum product variation purchase quantity. Default value is taken from a base product. Not visible if the value is not assigned. |
maxPurchaseQuantity | number | Sets maximum product variation purchase quantity. Default value is taken from a base product. Not visible if the value is not assigned. |
OptionValue
Field | Type | Description |
---|---|---|
name | string | Option name |
nameTranslated | <Translations> | Available translations for product option name |
value | string | Option value |
valueTranslated | <Translations> | Available translations for product option value |
ProductOptionChoice
Field | Type | Description |
---|---|---|
text | string | Option selection text, e.g. 'Green' |
textTranslated | <Translations> | Available translations for product option selection text |
priceModifier | number | Percent or absolute value of the option's price markup. Positive, negative and zero values are allowed. Default is 0 |
priceModifierType | string | Option markup calculation type. PERCENT or ABSOLUTE . Default is ABSOLUTE . |
Translations
Field | Type | Description |
---|---|---|
<ISO_LANG_CODE> | string | Translations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings |
ProductDimensions
Field | Type | Description |
---|---|---|
length | number | Length of a product |
width | number | Width of a product |
height | number | Height of a product |
SubscriptionSettings
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. |
displayedOneTimePurchaseMarkupPercent | number | The difference between the price of the product when subscribing and a one-time purchase as a percentage. Displayed in a badge in the product listing. |
displayedOneTimePurchaseMarkupPercentFormatted | string | The difference between the price of the product when subscribing and a one-time purchase as a percentage. Displayed in a badge in the product listing and formatted according to the settings for displaying prices in the store. |
recurringChargeSettings | <RecurringChargeSettings> | Recurring charge settings |
RecurringChargeSettings
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. |
TaxInfo
Field | Type | Description |
---|---|---|
taxable | boolean | true to apply taxes to this product, false otherwise |
defaultLocationIncludedTaxRate | number | Default tax rate (%) for including into product price. Is a sum of all enabled taxes included in product price for the store location. Read only |
enabledManualTaxes | Array<number> | Array of internal Ecwid tax IDs, as listed in Store profile. Empty array if no manual taxes are enabled or automatic taxes are enabled |
taxClassCode | string | A unique tax class code for the product that determine the taxability of the products for a certain region. If not specified the default value is Default |
NameYourPriceEnabled
Field | Type | Description |
---|---|---|
priceDefaultTier | number | Default price tier. |
customPriceTiers → value | Array | Sorted array of custom price tiers (value). |
Ribbon
Field | Type | Description |
---|---|---|
text | string | A small text, which is displayed in the product ribbon. Maximum length: 30 symbols |
color | string | Background color of the product ribbon |
Errors
In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description
HTTP codes
HTTP Status | Meaning | Code (optional) |
---|---|---|
400 | The cleanUrls value is invalid. It must be either true or false | CLEAN_URLS_PARAMETER_IS_INVALID |
403 | Access token doesn't have read_catalog scope | |
404 | Product is not found | |
500 | Cannot get the product because of an error on the server |
Error response body (optional)
Field | Type | Description |
---|---|---|
errorMessage | string | Error message |
Q: How to get URLs for products?
Direct URL for each product is always available in the url
field once you make a request to the Ecwid REST API.
In any Ecwid store there is a storefront URL field, where store owners can specify their storefront location.
In case if it's empty, Ecwid will use their Instant site URL to provide product URLs in the REST API and other connected services.
When a store is embedded into multiple websites
For this situation you may need to generate a product feed for each of those websites (building a sitemap, etc.), hence there will be multiple storefront URLs to process. In this case you can use baseUrl
request parameter to get a working product URL in a response from the Ecwid REST API.
Let's see how it works:
If baseUrl
request parameter is specified, then the url
field will be generated according to that URL as a storefront URL.
Examples
Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"
:
baseUrl
parameter is not set in a request:
Example product URL in the url
field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"
baseUrl
parameter is set as"https://mycoolstore.com"
:
Example product URL in the url
field will be: "https://mycoolstore.com#!/apple/p/70445445"
As you can see, the product URL in a response from Ecwid API changes based on the value of the baseUrl
request parameter. So now you can use it to get product URLs of the same store for any number of storefront URLs.
It is possible to use the baseUrl
parameter together with the cleanUrls
parameter. See below for more details on the cleanUrls
parameter.
Receiving SEO-friendly (clean) URLs from the Ecwid REST API
If Ecwid knows that the store uses SEO-friendly URLs format, the url
field in API responses will be using it: "https://mdemo.ecwid.com/apple-p70445445"
Alternatively, you will get URLs in a hash-based format: "https://mdemo.ecwid.com#!/apple/p/70445445"
.
If your website supports the SEO-friendly (clean) URLs, you will need to use the cleanUrls
request parameter in order to get URLs in that format.
In order for SEO-friendly (clean) URLs to be enabled on your website, please follow the instructions in SEO-friendly URLs.
Let's see how it works.
If cleanUrls
parameter is set in a request URL to true
, then url
field will have the SEO-friendly format in a response (clean URL, no hash "#"):
API Request format example: GET https://app.ecwid.com/api/v3/1003/products?token=secret_1234567890qwqeertt&cleanUrls=true
Examples
Ecwid store has a storefront URL set in store settings as: "https://mdemo.ecwid.com"
cleanUrls
parameter is set tofalse
or not set
Example product URL in the url
field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"
cleanUrls
parameter is set totrue
Example product URL in the url
field will be: "https://mdemo.ecwid.com/apple-p70445445"
As you can see, the format of a product URL returned from the Ecwid API changes based on the cleanUrls
request parameter. So now you can use it to get URLs of any of the two supported URL formats - SEO-friendly (clean) URLs or hash-based URLs.
It is possible to use the cleanUrls
parameter together with the baseUrl
parameter. See above for more details on the baseUrl
parameter.