put https://app.ecwid.com/api/v3//products/
Update an existing product in an Ecwid store referring to its ID.
You can use the checkLowStockNotification as a request parameter. If true, makes Ecwid check whether the low stock email notification needs to be sent to merchant after request is sent.
Access scopes
Requires the following access scope: update_catalog
Request
A JSON object with the following fields:
Product
| Field | Type | Description |
|---|---|---|
| sku | string | Product SKU |
| name | string | Product title |
| nameTranslated | Object translations | Available translations for product name |
| quantity | number | Amount of product items in stock. |
| unlimited | boolean | Set as true to make Unlimited stock for the product and to not track product inventory. |
| price | number | Base product price |
| wholesalePrices | Array<WholesalePrice> | Sorted array of wholesale price tiers (quantity limit and price pairs) |
| lowestPrice | number | Value of the product's "Lowest price" used for promotions. This value matches with the one displayed in Ecwid admin. |
| defaultDisplayedLowestPrice | number | Value of the lowest product price with applied taxes (lowestPrice + tax). Matches with the lowest product price displayed on the storefront. |
| defaultDisplayedLowestPriceFormatted | string | Formatted lowest price displayed on the storefront (defaultDisplayedLowestPrice). Uses store formatting settings.Example: "defaultDisplayedLowestPrice": 45 => "defaultDisplayedLowestPriceFormatted": "45.00". |
| compareToPrice | number | Product's sale price displayed strike-out in the customer frontend |
| 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 |
| nameYourPriceEnabled | boolean | Set to true to enable the "Name your price" feature allowing you to collect donations. Learn more |
| customPriceTiers | Object customPriceTiers | Defines fixed price values for the donations feature. Requires nameYourPriceEnabled setting to be enabled. |
| isShippingRequired | boolean | true if product requires shipping, false otherwise |
| tax | <TaxInfo> | Detailed information about product's taxes |
| weight | number | Product weight in the units defined in store settings. Leave empty for intangible products |
| customSlug | string | A custom slug set for the product URL. |
| productClassId | number | Id of the product type that this product belongs to. 0 value means the product is of the default 'General' type. See also: Product types and attributes in Ecwid |
| enabled | boolean | true to make product enabled, false otherwise. Disabled products are not displayed in the store front. |
| options | Array<ProductOption> | List of the product options. |
| 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 extra shipping cost the product adds to the global calculated shipping |
| shipping | <ShippingSettings> | Shipping settings of this product |
| description | string | Product description in HTML |
| descriptionTranslated | Object translations | Available translations for product description |
| galleryImages | Array<GalleryImages> | List of the product gallery images (for updating sort order) |
| media | <ProductMedia> | Sorting and alt text for product images. |
| categoryIds | Array<number> | List of the categories, which the product belongs to. If no categories provided, product will be displayed on the store front page, see showOnFrontpage field |
| 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 | Object translations | 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 | Object translations | Translations of the page description to be displayed in search results on the web |
| 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 |
| attributes | Array<AttributeValue> | Product attributes and their values |
| relatedProducts | <RelatedProducts> | Related or "You may also like" products of the product |
| dimensions | <ProductDimensions> | Product dimensions info |
| volume | number | Product volume, fractional number, 0 by default. |
| volumeUnit | string | The unit of measurement of the store's volume, possible values: l, ml, oz. ml 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 negative value means the product is not shown in the store front page |
| 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 | Array<SubscriptionSettings> | Subscription settings |
| subtitle | text | Short product description for categories or search pages. |
| ribbon | <Ribbon> | Small product label visible on categories and product pages. To delete the ribbon, send a request with an empty "text" field. Example: "text": "" |
| subtitleTranslated | Object translations | Available translations for product subtitles. |
| ribbonTranslated | Object translations | Available translations for product ribbons. |
| 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. |
| maxPurchaseQuantity | number | Sets maximum product purchase quantity. |
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 | Object 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. Passing the null value or omitting the field will keep the existing value unchanged. |
| required | boolean | true if this option is required, false otherwise. Default is false |
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 |
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) |
AttributeValue
| Field | Type | Description |
|---|---|---|
| id | number | Unique attribute ID. See Product Classes for the information on attribute IDs. |
| name | string | Can be used to specify the attribute. It's case-insensitive. If id or alias fields are sent, the field will be ignored. |
| nameTranslated | Object translations | Available translations for product attribute name |
| alias | string | One of UPC, BRAND, PRICE_PER_UNIT, UNITS_IN_PRODUCT. This can be used instead of id or name to quickly set the basic variation attributes without numeric id. |
| value | string | Attribute value same as the main store language. It can be empty when the other translations are updated. |
| valueTranslated | Object translations | Available translations for product attribute value. |
| show | string | Defines if an attribute is visible on a product page. Supported values: NOTSHOW, DESCR, PRICE. The value PRICE = DESCR. |
RelatedProducts
| Field | Type | Description |
|---|---|---|
| productIds | Array<number> | IDs of the related products, sort order is taken into the account |
| productSkus | Array<string> | SKUs of the related products. Write-only. Products added via SKUs will be displayed in the productIds array. |
| 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 |
OptionValue
| Field | Type | Description |
|---|---|---|
| name | string | Option name, as in Product.options[i].name |
| nameTranslated | Object translations | Available translations for product option name |
| value | string | Option value one of Product.options[i].choices[j].text |
| valueTranslated | Object translations | Available translations for product option value |
ProductOptionChoice
| Field | Type | Description |
|---|---|---|
| text | string | Option selection text, e.g. 'Green' |
| textTranslated | Object 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. |
ProductMedia
| Field | Type | Description |
|---|---|---|
| images | Array <ProductImage> | Sorting and alt text for product images. Any changes to orderBy and alt requires all image IDs to be listed in the update request. |
ProductImage
| Field | Type | Description |
|---|---|---|
| id | number | Internal image ID |
| alt | <ProductImageAlt> | Image description in "alt" attribute and its translations. |
| 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 |
ProductImageAlt
| Field | Type | Description |
|---|---|---|
| main | string | Text image description displayed in "alt" image attribute |
| translations | Object translations | Translations for the "alt" image description |
translations
Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. Example:
{
"en": "Sample text",
"nl": "Voorbeeldtekst"
}
Translations for each available language. If no other translations are provided, the default language translations is returned. See available languages in store language settings.
customPriceTiers
An object containing arrays with only one value field. Values here determine available "Fixed price" options for the product. Learn more
Code example:
"customPriceTiers": [
{
"value": 25
},
{
"value": 50
},
{
"value": 100
}
]
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. |
| 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 |
|---|---|---|
| enabledManualTaxes | Array<TaxId> | Array of internal Ecwid tax IDs, as listed in Store profile. Empty array if no manual taxes are enabled or automatic taxes are enabled |
| taxable | boolean | true to apply taxes to this product, false otherwise |
| 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, can not be empty. If the passed code is not valid for merchant's region, returns error Tax class is not found |
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, accepts following formats: #RGB, #RRGGBB, #RGBA, #RRGGBBAA |
Response
A JSON object of type 'UpdateStatus' with the following fields:
UpdateStatus
| Field | Type | Description |
|---|---|---|
| updateCount | number | The number of updated products (1 or 0 depending on whether the update was successful) |
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 | Description | Code (optional) |
|---|---|---|
| 400 | Request parameters are malformed | |
| 400 | Attribute showOnFrontpage was specified as a negative number when there are no categories assigned to product | Attribute showOnFrontpage can’t be negative, because the product has no categories |
| 402 | The functionality/method is not available on the merchant plan | |
| 402 | The merchant plan product limit is reached | |
| 403 | Access token doesn't have update_catalog scope | |
| 404 | Some of the linked entities in the request doesn't exist. For example, the product class is not found | |
| 409 | The product with such SKU already exists | SKU_ALREADY_EXISTS |
| 409 | Specified wholesale price can't be null | WHOLESALE_PRICES_CANT_BE_NULL |
| 409 | Specified wholesale price can't be negative | WHOLESALE_PRICES_CANT_BE_NEGATIVE |
| 409 | Specified wholesale price is too big | WHOLESALE_PRICES_TOO_BIG |
| 409 | Specified wholesale price quantity is too small | WHOLESALE_PRICES_QUANTITY_TOO_SMALL |
| 409 | Specified manual taxes cannot be assigned because store has automatic taxes enabled | |
| 409 | Specified manual taxes cannot be assigned because this tax is disabled in store | |
| 415 | Unsupported content-type: expected application/json or text/json |
Error response body (optional)
| Field | Type | Description |
|---|---|---|
| errorMessage | string | Error message |
| errorCode | string | Error code |