Get a product

Get all details of a specific product in an Ecwid store by its ID.

Headers

NameTypeDescription
AuthorizationstringoAuth 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.

Q: How can I specify what fields I want to receive in response?

Add responseFields query param, specifying field names you want to receive.
Example: ?responseFields=id,sku,quantity

Query parameters

FieldTypeDescription
baseUrlstringStorefront 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
langstringPreferred 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.
cleanUrlsbooleanIf 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
slugsWithoutIdsbooleanSet true to receive custom page slug

Response

A JSON object of type 'Product' with the following fields:

Product

FieldTypeDescription
idnumberUnique integer product identifier
skustringProduct SKU. Items with options can have several SKUs specified in the product variations
quantitynumberAmount 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).
unlimitedbooleantrue if the product has unlimited stock
inStockbooleantrue if the product or any of its variations is in stock (quantity is more than zero) or has unlimited quantity. false otherwise.
namestringProduct title
nameTranslated<Translations>Available translations for product name
pricenumberBase product price
defaultDisplayedPricenumberProduct 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
defaultDisplayedPriceFormattedstringFormatted display of defaultDisplayedPrice in the store's formatting for prices
costPricenumberPurchase 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
wholesalePricesArray<WholesalePrice>Sorted array of wholesale price tiers (quantity limit and price pairs)
lowestPricenumberThe lowest price for the last 30 days before discount.
defaultDisplayedLowestPricenumberlowestPrice with tax
defaultDisplayedLowestPriceFormattedstringFormatted display of defaultDisplayedLowestPrice in the store's formatting for prices
compareToPricenumberProduct's sale price displayed strike-out in the customer frontend Omitted if empty
compareToPriceFormattedstringFormatted display of compareToPrice in the store's formatting for prices
compareToPriceDiscountnumberSale price discount amount
compareToPriceDiscountFormattedstringSale price formatted discount amount (with store currency)
compareToPriceDiscountPercentnumberSale price discount percent
compareToPriceDiscountPercentFormattedstringSale price discount percent (with percent sign)
isShippingRequiredbooleantrue if product requires shipping, false otherwise
weightnumberProduct weight in the units defined in store settings. Omitted for intangible products
urlstringURL of product details page in the storefront. URL will be provided in SEO-friendly format if Ecwid knows the store uses them.
createdstringDate and time of the product creation. Example: 2014-07-30 10:32:37 +0000
updatedstringProduct last update date/time
createTimestampnumberThe date of product creation in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberProduct last update date in UNIX Timestamp format, e.g 1427268654
productClassIdnumberId 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
enabledbooleantrue if product is enabled, false otherwise. Disabled products are not displayed in the store front.
optionsArray<ProductOption>A list of the product options. Empty ([]) if no options are specified for the product.
warningLimitnumberThe 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.
fixedShippingRateOnlybooleanLegacy 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
fixedShippingRatenumberLegacy 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
defaultCombinationIdnumberIdentifier of the default product variation, which is defined by the default values of product options.
originalImageArray<OriginalImage>Original image information
descriptionstringProduct description in HTML
descriptionTranslated<Translations>Available translations for product description
galleryImagesArray<GalleryImages>List of the product gallery images (for updating alt tags and sort order)
media<ProductMedia>Media files for a product (images)
categoryIdsArray<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
categoriesArray<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
defaultCategoryIdnumberDefault category ID of the product. If value is 0, then product does not have a default category and is not shown anywhere in storefront
seoTitlestringPage 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
seoTitleTranslatedstringTranslations of the page title to be displayed in search results on the web
seoDescriptionstringPage 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
seoDecriptionTranslatedstringTranslations of the page description to be displayed in search results on the web
favorites<FavoritesStats>Product favorites stats
attributesArray<AttributeValue>Product attributes and their values
filesArray<ProductFile>Downloadable files (E-goods) attached to the product
relatedProducts<RelatedProducts>Related or "You may also like" products of the product
combinationsArray<Variation>List of the product variations
dimensions<ProductDimensions>Product dimensions info
volumenumberProduct volume, fractional number, 0 by default.
showOnFrontpagenumberA 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)
isSampleProductbooleantrue if this product is a sample one (sample product when Ecwid store is initially created). false otherwise. Read only field
isGiftCardbooleantrue if a product is a gift card. false if it's a regular store product. Read only field
discountsAllowedbooleantrue if Ecwid can apply discounts to this product at checkout. false otherwise
nameYourPriceEnabledbooleantrue if the "Pay What You Want " feature is enabled. false otherwise.
subscriptionSettings<SubscriptionSettings>Subscription settings
subtitletextShort 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.
externalReferenceIdstringExternal ID for products synced from external services (e.g. POS)
customsHsTariffCodestringProduct code for customs reference. Omitted if empty
outOfStockVisibilityBehaviourstringIndicates whether an out of stock product should visible or not. One of: SHOW, HIDE, ALLOW_PREORDER.
minPurchaseQuantitynumberSets minimum product purchase quantity. null by default. Not visible if the value is not assigned.
maxPurchaseQuantitynumberSets maximum product purchase quantity. null by default. Not visible if the value is not assigned.

LocationInventory

FieldTypeDescription
<X-seriese_location_ID>numberThe actual amount of product items in the location's stock

FavoritesStats

FieldTypeDescription
countnumberThe actual number of 'likes' of this product
displayedCountstringThe 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

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

ProductOption

FieldTypeDescription
typestringOne of SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES, SIZE
namestringProduct option name, e.g. Color
nameTranslated<Translations>Available translations for product option name
choicesArray<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)
defaultChoicenumberThe number, starting from 0, of the option's default selection. Only presents if the type is SELECT or RADIO or SIZE
requiredbooleantrue 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

FieldTypeDescription
typestringOne 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.
methodMarkupnumberAdditional cost for shipping methods set by merchant (global and selected)
flatRatenumberFlat rate cost for shipping this product
disabledMethodsArray of stringIDs of shipping methods that need to be excluded from calculation when this product is in cart. IDs can be retrieved in Store profile
enabledMethodsArray of stringIDs 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

FieldTypeDescription
urlstringUrl of an original image
widthnumberWidth of an image (px)
heightnumberHeight of an image (px)

GalleryImages

FieldTypeDescription
idnumberId of an image in the gallery
urlstringURL of an image
thumbnailstringURL of a thumbnail (160px)
originalImageUrlstringURL of an original image
imageUrlstringURL of an image (1200px)
hdThumbnailUrlstringURL of an HD-thumbnail (800px)
thumbnailUrlstringURL of a big thumbnail (400px)
smallThumbnailUrlstringURL of a thumbnail (160px)
widthnumberWidth of an image (px)
heightnumberHeight of an image (px)
orderBynumberConsecutive number of an image in the gallery
borderInfoArray<BorderInfo>Border information

BorderInfo

FieldTypeDescription
dominatingColorArray<DominatingColor>Dominating color information
homogeneitybooleantrue if an image is homogeneous. false otherwise

DominatingColor

FieldTypeDescription
rednumberRed color (from 0 to 255, RGB)
greennumberGreen color (from 0 to 255, RGB)
bluenumberBlue color (from 0 to 255, RGB)
alphanumberAlpha channel (from 0 to 255)

ProductMedia

FieldTypeDescription
imagesArray <ProductImage>Images of this product and their details
videosArray <ProductVideo>Videos of this product and their details

ProductImage

FieldTypeDescription
idnumberInternal image ID
alt<ProductImageAlt>Image "alt" attribute and its translations
orderBynumberThe sort weight of the image in the gallery images list. The less the number, the closer the image to the beginning of the gallery
isMainbooleantrue if this is a main product image. false if gallery image
image160pxUrlstringURL of the product thumbnail resized to fit 160x160px
image400pxUrlstringURL 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
image800pxUrlstringProduct HD thumbnail URL resized to fit 800x800px
image1500pxUrlstringURL of the product image resized to fit 1500x1500px
imageOriginalUrlstringURL of the image in its original resolution

ProductImageAlt

FieldTypeDescription
mainstringText image description displayed in "alt" image attribute
translations<Translations>Translations for the "alt" image description

ProductVideo

FieldTypeDescription
idnumberInternal video ID
videoCoverIdnumberID of the cover image for the video (from 'images')
urlbooleanURL to the video file
embedHtmlstringEmbedded code for the video file
providerNamestringVideo hosting provider name (could be empty)
titlestringVideo title (could be empty)
image160pxUrlstringURL of the video cover image resized to fit 160x160px
image400pxUrlstringURL of the video cover image resized to fit 400x400px
image800pxUrlstringURL of the video cover image resized to fit 800x800px
image1500pxUrlstringURL of the video cover image resized to fit 1500x1500px
imageOriginalUrlstringRL of the video cover image in its original resolution

CategoriesInfo

FieldTypeDescription
idnumberCategory ID
enabledbooleantrue if category is enabled, false otherwise

AttributeValue

FieldTypeDescription
idnumberUnique attribute ID. See Product types for the information on attribute IDs
namestringAttribute displayed name
nameTranslated<Translations>Available translations for product attribute name
valuestringAttribute value
valueTranslated<Translations>Available translations for product attribute value
typestringAttribute 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
showstringDefines if an attribute is visible on a product page. Supported values: NOTSHOW, DESCR, PRICE. The value PRICE = DESCR.

ProductFile

FieldTypeDescription
idnumberInternal ID of the file
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringDirect 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

FieldTypeDescription
productIdsArray<number>IDs of the related products
relatedCategoryRelatedCategoryDescribes the "N random related products from a category" option

RelatedCategory

FieldTypeDescription
enabledbooleantrue if the "N random related products from a category" option is enabled. false otherwise
categoryIdnumberId of the related category. Zero value means "any category", that is, random products from the whole store.
productCountnumberNumber of random products from the given category to be shown as related

Variation

FieldTypeDescription
idnumberVariation ID
combinationNumbernumberVariation # number, which is displayed in the variations table in Control panel
optionsArray<OptionValue>Set of options that identifies this variation. An array of name-value pairs
skustringVariation SKU. Omitted if the variation inherits the base product's SKU
thumbnailUrlstringURL 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.
imageUrlstringURL 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.
smallThumbnailUrlstringURL 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.
hdThumbnailUrlstringProduct variation HD thumbnail URL resized to fit 800x800px. Omitted if the variation inherits the base product's image.
originalImageUrlstringURL of the original not resized product variation image. Omitted if the variation inherits the base product's image.
quantitynumberAmount 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.
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product's price.
wholesalePricesArray<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.
weightnumberVariation weight in the units defined in store settings. Omitted if the variation inherits the base product's weight.
warningLimitnumberThe 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
attributesArray<AttributeValue>Variation's UPC attribute and its value
compareToPricenumberVariation's sale price displayed strike-out in the customer frontend Omitted if empty
minPurchaseQuantitynumberSets minimum product variation purchase quantity. Default value is taken from a base product. Not visible if the value is not assigned.
maxPurchaseQuantitynumberSets maximum product variation purchase quantity. Default value is taken from a base product. Not visible if the value is not assigned.
outOfStockVisibilityBehaviourstringIndicates whether an out of stock product should visible or not. One of: SHOW, HIDE, ALLOW_PREORDER.

OptionValue

FieldTypeDescription
namestringOption name
nameTranslated<Translations>Available translations for product option name
valuestringOption value
valueTranslated<Translations>Available translations for product option value

ProductOptionChoice

FieldTypeDescription
textstringOption selection text, e.g. 'Green'
textTranslated<Translations>Available translations for product option selection text
priceModifiernumberPercent or absolute value of the option's price markup. Positive, negative and zero values are allowed. Default is 0
priceModifierTypestringOption markup calculation type. PERCENT or ABSOLUTE. Default is ABSOLUTE.

Translations

FieldTypeDescription
<ISO_LANG_CODE>stringTranslations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings

ProductDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

SubscriptionSettings

FieldTypeDescription
subscriptionAllowedbooleantrue if the product can be sold as subscription ("Sell as subscription" product setting enabled). false otherwise.
oneTimePurchaseAllowedbooleantrue if the product can be purchased once, with no further charges on a regular basis. false otherwise.
oneTimePurchasePricenumberThe cost of the product by subscription with a one-time purchase, null by default.
oneTimePurchasePriceFormattedstringThe cost of the product for a one-time purchase, formatted according to the settings for displaying prices in the store.
oneTimePurchaseMarkupnumberThe 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.
oneTimePurchaseMarkupFormattedstringThe 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.
oneTimePurchaseMarkupPercentnumberThe 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.
oneTimePurchaseMarkupPercentFormattedstringThe 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.
displayedOneTimePurchaseMarkupPercentnumberThe 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.
displayedOneTimePurchaseMarkupPercentFormattedstringThe 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

FieldTypeDescription
recurringIntervalstringCharge recurring interval. Supported values: DAY, WEEK, MONTH, YEAR.
recurringIntervalCountnumberCharge recurring interval. Supported values: for DAY - 1 (daily), for WEEK - 1 (weekly), 2 (biweekly), for MONTH - 1 (monthly), 3 (quarterly), for YEAR - 1 (annually).
subscriptionPriceWithSignUpFeenumberThe cost of the product for the first subscription order.
subscriptionPriceWithSignUpFeeFormattedstringThe 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.
signUpFeenumberThe size of the markup that is imposed on the first order.
signUpFeeFormattedstringThe 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

FieldTypeDescription
taxablebooleantrue to apply taxes to this product, false otherwise
defaultLocationIncludedTaxRatenumberDefault tax rate (%) for including into product price. Is a sum of all enabled taxes included in product price for the store location. Read only
enabledManualTaxesArray<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
taxClassCodestringA 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

FieldTypeDescription
priceDefaultTiernumberDefault price tier.
customPriceTiers → valueArraySorted array of custom price tiers (value).

Ribbon

FieldTypeDescription
textstringA small text, which is displayed in the product ribbon. Maximum length: 30 symbols
colorstringBackground 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 StatusMeaningCode (optional)
400The cleanUrls value is invalid. It must be either true or falseCLEAN_URLS_PARAMETER_IS_INVALID
403Access token doesn't have read_catalog scope
404Product is not foundPRODUCT_NOT_FOUND
500Cannot get the product because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError 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 to false or not set

Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"

  • cleanUrls parameter is set to true

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.

Language
Authorization
Query