post https://app.ecwid.com/api/v3//products
Create a new product
Access scopes
Requires the following access scope: create_catalog
Request
A JSON object with the following fields:
Parameters in bold are mandatory
Product
| Field | Type | Description |
|---|---|---|
| name | string | Product title |
| nameTranslated | <Translations> | Available translations for product name |
| sku | string | Product SKU. If this field is empty, Ecwid will generate new unique SKU automatically. |
| 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. |
| tax | <TaxInfo> | Detailed information about product's taxes |
| isShippingRequired | boolean | true if product requires shipping, false otherwise |
| customSlug | string | A custom slug set for the product URL. |
| weight | number | Product weight in the units defined in store settings. Leave empty for intangible products |
| 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 to make product enabled, false otherwise. Disabled products are not displayed on the storefront. If not passed, the default value is false. |
| 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 an 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 | <Translations> | Available translations for product description |
| 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 | 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 |
| seoDescriptionTranslated | string | 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. If no categories are assigned to product in categoryIds field, the showOnFrontPage will be 1 |
| 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. |
| subtitleTranslated | <Translations> | Available translations for product subtitles. |
| ribbonTranslated | <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. null by default. |
| maxPurchaseQuantity | number | Sets maximum product purchase quantity. null by default. |
| reviewsCollectingAllowed | boolean | true to allow to collect, check, and publish reviews for this product in store. |
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 and is required in this case |
| required | boolean | true if this option is required, false otherwise. Default is false |
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
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
}
]
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 |
WholesalePrice
| Field | Type | Description |
|---|---|---|
| quantity | number | Number of product items on this wholesale tier |
| price | number | Product price on the tier |
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 | <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 |
| valueTranslated | <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 |
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<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 |
| taxable | boolean | true to apply taxes to this product, false otherwise |
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 |
Response
A JSON object of type 'CreateStatus' with the following fields:
CreateStatus
| Field | Type | Description |
|---|---|---|
| id | number | ID of the created product |
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 | |
| 402 | The functionality/method is not available on the merchant plan | |
| 402 | The merchant plan product limit is reached. If the store has reached the product limit and some products have been deleted, this error can still appear for 2 minutes after the DELETE request. | MAX_PRODUCTS_FOR_API_REQUEST_LIMIT_EXCEEDED |
| 403 | Access token doesn't have create_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 |