get https://app.ecwid.com/api/v3//products/
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":
baseUrlparameter is not set in a request:
Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"
baseUrlparameter 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"
cleanUrlsparameter is set tofalseor not set
Example product URL in the url field will be: "https://mdemo.ecwid.com#!/apple/p/70445445"
cleanUrlsparameter 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.