Manual for Icecat Push-API (API-IN)

In this manual, we provide a guide on how to push product information into the Icecat PIM or Vendor Central via Icecat’s JSON API-IN or Push-API.

This Push-API is primarily intended for the automated ingestion of a brand owner’s product information, which is subsequently syndicated to a brand owner’s channel partners. The idea of the Push-API is to make it easy to push product content to our PIM system and integrate it’s multilingual and global content publication functionalities within a brand owner’s workflows and master data management processes.

Further, the Push-API is extensively used within Icecat’s ecosystem between editor, ETL and other applications and Icecat’s multimedia PIM environment. The Push-API is stress-tested, but of course still gradually evolving.

About Icecat

Icecat – is a unique open and multi-lingual catalog and PIM with millions of multilingual product data-sheets. Icecat product data can be integrated within online shops, ERPs, purchase systems, comparison sites, blogs and other apps. The Icecat product data is fully standardized and allows categorization, filtering, search and product comparisons. Moreover, Icecat provides content optimization, increases shop conversion and makes online shopping easier and more fun, especially when including multimedia content.

Our Global Mission: Product Content that Helps Buyers Decide, in any language, in any country, on any media.

About this Push-API

The Icecat Push-API is supporting a full list of content elements or digital asset types as maintained by Icecat. E.g.,

• basic product information
• product images
• marketing texts and descriptions
• product features
• videos
• manuals
• leaflets
• reasons to buy
• bullet points
• 3D
• product pages (html5 minisites)
• Etc.

Basically, any data or digital asset that is needed to understand or process a brand’s product.

Please note that in Push-API calls, you may need to refer to some output from previous API calls. Take care of properly processing and storing the output. 

Content journey map

Before pushing the content to the Icecat API, you need to map your content to the Icecat API calls. The content on our side are distinguished by key factors:

• Language (locale) specific versus non-language (locale) specific content. See the overview of languages and locales supported.
• Category specific content versus generic content

Pushing your category specific data to Icecat may require adaptation of our taxonomy and introduction of new entries to existing list-of-values (LOVs).

 

There are certain dependencies in the calls which determine the order of the content push through Icecat API, that is also visualized on the schema above.

In a nutshell, the process can be split into 3 major steps

1. Create the basic product record

Product identification (Brand + Brand Product Code), categorization and attribution to Families and series is done here. Providing categorization will enable one to add category-specific content (product specs). 

When a product record is created, the Icecat internal product ID is created to uniquely identify the product record in Icecat’s PIM. You will need to refer to it from here on, so it’s important to store it. Alternatively, you can also look it up by using the product search API.

In all further calls, you will need to refer to the created Icecat product ID.

2. Push international / language-independent content

In this step, you define the DRM (digital rights management) settings, additional product identifiers (GTINs), the product life cycle, and product cross-sell relations (the related products should be already present in Icecat). 

In this step, you may push language-independent product images and product specs. 

3. Language-dependent content

The last step is to add your marketing messaging data: model descriptions, product descriptions, reasons-to-buy, bullet points, etc. 

Please, always remember that what you’re pushing in Icecat is becoming accessible to connected and authorized retailers. That means that pushing incorrect data or incomplete product content for live products may impact their businesses in a negative way, while doing the data pushes accurately and complete will help them to have better performance and more deals.

Publication restrictions for not yet released products is a good idea to prevent dissemination of incorrect or incomplete data.

Collaboration with the Icecat team

During the process of content integration, you may need assistance or cooperation with the Icecat team.

It’s important to understand with whom you might need to interact when.

Account manager	The account manager will help answering general questions, supports the account setup, and will navigate you through the Icecat team.
Taxonomy team	Maintains the taxonomy: creating/updating categories, product families, specification models, LOVs for certain specs, and all other taxonomy questions.
Editor team	Support with standardizing and improving product data-sheets.
Technical support	Questions regarding this API.

Push-API Overview

Below, a quick overview of the workflow related to using the Push-API and functionalities supported for the product data flow, which will be further described in following sections:

1. User authorization
2. Product search / identification
3. Create, update or view generic product record
4. Create, read, update or delete “Product model description”
5. Create, read, update or delete “Release date” and  “End of life date”
6. View, update or delete “Product personalized access” for assigned resellers
7. View, create, update or delete product “GTIN”
8. View, create, update or delete product features (Specs)
9. Add new value to restricted values list
10. View, create or update product multimedia objects (MMO)
11. View, create, update or delete product description block
12. View, create, update and delete “Reasons to buy” (Product bullets)
13. View, create and update product images (Gallery)
14. View, create, update and delete product relations

1. User authorization

Before you can start pushing the data you first have to authenticate yourself to the API by getting the session key. This session key you will need to use in further requests so API can authenticate you.  

Your account may have two-factor authorization (2FA) configured for a better security. For the protection of your account we recommended to protect your account by activating 2FA. See also Google authenticator: https://chrome.google.com/webstore/detail/authenticator/bhghoamapcdpbohphigoooaddinpkbai

1.1. Registration of a user account

To register a new user account with a brand role please, first register here if you don’t have an Icecat account yet and in all cases contact your Icecat account manager as your account needs to be authorized for pushing a brand’s product data to Icecat.

1.2. Check 2FA for your account

Swagger schema – https://api.icecat.biz (LoginInfo)
Request:

URL:	https://bo.icecat.biz/restful/v3/LoginInfo/{{Login}}
Method:	GET

Success response:

Status	Body	Comment
200	{ “Data”: { “2FA”: true }}	Two factor authorization required for current login
200	{ “Data”: { “2FA”: false }}	Two factor authorization is not needed for current “Login”

1.3. User login for an account without 2FA activated

Request:

URL:	https://bo.icecat.biz/restful/v3/Session
Method:	POST
Body:	{ “Login”: “{{Login}}”, “Password”: “{{Password}}”, “SessionType”: “Perl”}

Success response:

Status:	201
Body:	{ “Data”: { “SessionId”: “{{SessionId}}” }}

Error responses:

Status	Body	Comment
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Login is not found”}	User input incorrect login
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Password is incorrect”}	User input incorrect login
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “SessionType is invalid”}	User input incorrect SessionType. Note. Always used “SessionType”:”Perl”
429	{ “Code”: 429, “Error”: “Too Many Requests”, “Message”: “Too many authentication attempts. Please try again in 300 seconds”}	Detected 6 unsuccessful authentication attempts in the last 2 minutes. The next authentication attempt will be allowed after 5 minutes.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ 2FAKey is not needed “}	User input sent body with the parameter 2FAKey, but the account isn’t 2FA activated via its user profile.

1.4. User login for an account with 2FA activated

Request:

URL:	https://bo.icecat.biz/restful/v3/Session
Method:	POST
Body:	{ “Login”: “{{Login}}”, “Password”: “{{Password}}”, “SessionType”: “Perl”, “2FAKey”:”{{2FAKey}}»}

Success response:

Status:	201
Body:	{ “Data”: { “SessionId”: “{{SessionId}}” }}

Error responses:

Status	Body	Comment
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Login is not found”}	User input: incorrect login.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Password is incorrect”}	User input: incorrect password.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “SessionType is invalid”}	User input: incorrect SessionType. Note. Always used “SessionType”:”Perl”
429	{ «Code»: 429, «Error»: «Too Many Requests», «Message»: «Too many authentication attempts. Please try again in 300 seconds»}	Detected 6 unsuccessful authentication attempts in the last 2 minutes, the next authentication attempt will be allowed after 5 minutes.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “2FAKey is required for you“}	For your user account 2FA is activated. You should send the 2FA Key to login successfully.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “2FAKey must be a 6-digit string”}	User input: incorrect 2FAKey, not equal to 6-digit string.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “2FAKey is incorrect”}	User input: incorrect 2FAKey, but equal to 6-digit string.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “2FAKey is required for you”}	User input: sent body without required parameter 2FAKey.

2. Product search

Before pushing a product content to Icecat you need to verify if such product record already exists at Icecat. 

Checking if a product exists in the products index is done through the Product Search API. The lookup is done by the identifiers: 

• GTIN (EAN/UPC/JAN identifiers)
• Brand Product Code (Manufacturer part numbers – MPN) + BrandId (SupplierID)

No mappings are applied to the input parameters during the search.

If you can’t find the product, you can create it, and otherwise you have to update the record that is already existing. Please, note that updating someone else’s product may require additional permissions.

Swagger schema – https://api.icecat.biz (Product search)
In our practice we are using the following terminology:

• EAN and GTIN are used as synonyms (GTIN is the correct term of course)
• MPN is the Brand Product code
• Supplier is the Brand

Request:

URL:	https://bo.icecat.biz/restful/v3/Productsearch?AccessKey={{SessionId}}
Method:	POST
Body:	{ “Eans”: [“{{EAN}}”, …], “Mpns”: [“{{MPN}}”, …], “SupplierId”: {{SupplierId}}}
Comment:	{{EAN}} – one should use GTIN (EAN)-8,12,13 or EAN-14 for searching. {{MPN}} and {{SupplierID}} – one should use these parameters jointly for more accurate searche results. SupplierID – See 2.1. You can execute product’s searching by EAN or MPN only, but for more effective searching one should use all parameters.

Success response:

Status:	200
Body:	{ “Data”: { “Products”: [ { “Eans”: [ “{{EAN}}” ], “ProductId”: {{ProductId}} }, … { “Mpns”: [ “{{MPN}}” ], “ProductId”: {{ProductId}} }, … ] }}
Comment:	Products exist in the database. In the response you will get the ProductId for this product or these products.
Status:	200
Body:	{ “Data”: { “Products”: [ ] // empty }}
Comment:	Products with requested EANs and MPNs are absent in the Icecat database.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	Input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Mpns can’t be empty when brand is present.”}	Request body contains the parameter “SupplierId” without the parameter “MPNs”.

2.1. Get available SupplierID (BrandID) for a user (with user role “brand”)

User accounts with the role “brand” can view, create or update products only for the Brands they are assigned to. For assigning your user account to the respective Brand, please contact your Icecat account manager.

Request:

URL:	https://bo.icecat.biz/restful/v2/Brand?type=brand&access_key={{SessionId}}
Method:	GET
Comment:	If you received an empty response, it means that your account is not assigned to any Brand.

Success response:

Status:	200
Body:	{ “Data”: [ { “BrandId”: “{{SupplierId}}”, “Name”: “{{Brand Name}}” }, … ]}
Comment:	The response contains a full list of the Brands allowed for your user account.
Status:	200
Body:	{ “Data”: [ ] }
Comment:	If you received an empty response, it means that your account is not assigned to any Brand.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
501	{ “Code”: 501, “Error”: “Not Implemented”, “Message”: “Type: {{Type}} isn’t implemented”}	User input: incorrect value for query parameter “Type”.

In case that you are creating a new product please see 2.2. If you’re updating an existing product please read 2.3. for updating the “General” product record.

Accounts with user role “brand” can’t delete products from the Icecat database.

2.2. Create a new product record

Note. accounts with as user role “brand” can create a product only for the Brands they are assigned to.

Request:

URL:	https://bo.icecat.biz/restful/v3/Product?AccessKey={{SessionId}}
Method:	POST
Body:	{ “PartCode”: “{{MPN}}”, – mandatory “BrandId”: “{{SupplierId}}”, – mandatory “CategoryId”: “{{CategoryId}}”, – mandatory “IsDangerous”: {{IsDangerous}}, – mandatory “UserId”: “{{UserId}}”, – mandatory “Publish”: “{{Publish}}”, – mandatory “VirtualCategories”: [“{{VirtualCategoryId}}”,…  ], – optional “FamilyId”: “{{FamilyId}}”, – optional or mandatory “SeriesId”: “{{SeriesId}}” – optional}
Comment:	{{SupplierID}} – see 2.1. (BrandId) {{CategoryId}} – see 2.2.1. {{IsDangerous}} – (Boolean) true – means that the product has a dangerous property (in this case the /restful/v3/ProductDescriptions parameter “disclaimer” is mandatory); false – means that the product hasn’t any dangerous properties. {{UserId}} – see 2.2.2. {{Publish}} – for accounts with user role “brand” only two values are allowed: “L”(Limited) – means the product will be allowed only for shop accounts which are authorized by the Brand, “Y”(Yes) –   means that product access is allowed for all shop accounts. {{VirtualCategoryId}} – see 2.2.3. {{FamilyId}} – see 2.2.4. and 2.2.5. {{SeriesId}}– see 2.2.6.

Success response:

Status:	200
Body:	{ “PartCode”: “{{MPN}}”, “BrandId”: “{{SupplierId}}”, “CategoryId”: “{{CategoryId}}”, “IsDangerous”: {{IsDangerous}}, “UserId”: “{{UserId}}”, “FamilyId”: “{{FamilyId}}”, “SeriesId”: “{{SeriesId}}”, “Publish”: “{{Publish}}”, “VirtualCategories”: [“{{VirtualCategoryId}}”,… ], “ProductName”: “{{ProductName}}”, “ProductId”: “{{ProductId}}”}
Comments:	Accounts with user role “brand” don’t have the ability to create or update the International product name and “{{ProductName}}” always will be equal to “{{MPN}}”{{ProductId}} – Internal Icecat product identifier.

Error response:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input is incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries to create a product for a brand for which it is not authorized.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Part number {{MPN}} is not unique. Another product with product id: {{ProductId}} was found”}	User tries to create a product with an MPN and SupplierId which already exists in the Icecat database
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Part number should be mapped, according to the product map rules”}	User tries to create a product with MPN and SupplierId for which already a mapping rule exists and a the mapped-to product already exists in the Icecat database.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not Found {{BrandId | CategoryId | UserId | FamilyId | SeriesId}}”}	User input: incorrect {{SupplierId}} , {{CategoryId}},{{UserId}},{{FamilyId}},{{SeriesId}}{{FamilyId}} is not assigned to brand and category, product{{SeriesId}} is not  assigned to this {{FamilyId}}

2.2.1. Get available CategoryId for user (user role “brand”) by user session

Note. The accounts with the user role “brand” can create a product only for Brands they are authorized to.

Request:

URL:	https://bo.icecat.biz/restful/v2/category?type=brand&access_key={{SessionId}}
Method:	GET
Comment:	This request should be used for getting only the categories which are recommended for the current user account
URL:	https://bo.icecat.biz/restful/v2/category?type=all&access_key={{SessionId}}
Method:	GET
Comment:	This request should be used for getting all product categories which exist in the Icecat database.

Success response:

Status:	200
Body:	{ “Data”: [ { “CategoryId”: “{{CategoryId}}”, “Name”: “{{CategoryName}}”, “Unspsc”: “{{UNSPSC}}”, “Disabled”: false|true }, … ]}
Comment:	If the current category has the status “Disabled”: false – this means that this category can’t be used for adding or updating the product.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

2.2.2. Get your UserId by user session

Note: accounts with user role “brand” should create products only with product “Owner” equal to its own UserId.

Request:

URL:	https://bo.icecat.biz/restful/v3/Users?Type=Info&AccessKey={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{ “Data”: { “UserId”: “{{UserId}}”, “Login”: “{{Login}}”, “UserGroup”: “supplier” }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
501	{ “Code”: 501, “Error”: “Not Implemented”, “Message”: “Type: {{Type}} isn’t implemented”}	User input: incorrect value for query parameter “Type”

2.2.3. GET available VirtualCategoryId by product CategoryId

Note: for creating a product one can only add Virtual categories which refer to the selected product Category.

Request:

URL:	https://bo.icecat.biz/restful/v2/virtualcategories?category_id={{CategoryId}}&type=general&access_key={{SessionId}}
Method:	GET
Comment:	{{CategoryId}} – Look at the p.2.2.1.

Success response:

Status:	200
Body:	{ “Data”: [ { “VirtualCategoryId”: “{{VirtualCategoryId}}”, “VirtualCategoryName”: “{{VirtualCategoryName}}” }, … ]}
Comment:	The response contains a full list of the Virtual categories allowed for the selected category only.
Status:	200
Body:	{ “Data”: []}
Comment:	If you received an empty response, it means that there are no virtual categories for the selected category. If you want to add new virtual categories to this category, please contact the taxonomy team.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not found by category_id”}	User set an absent {{CategoryId}}
501	{ “Code”: 501, “Error”: “Not Implemented”, “Message”: “Type: {{Type}} isn’t implemented”}	User input: incorrect value for query parameter “Type”

2.2.4. GET available FamilyId by the product SupplierID and CategoryId

Note: for some SupplierID the FamilyId could be a mandatory parameter for creating a product, please see 2.2.4.*
Request:

URL:	https://bo.icecat.biz/restful/v2/productfamily?brand_id={{SupplierID}}&category_id={{CategoryId}}&type=general&access_key={{SessionId}}
Method:	GET
Comment:	{{SupplierID}} – see 2.1. {{CategoryId}} – see 2.2.1.

Success response:

Status:	200
Body:	{ “Data”: [ { “FamilyId”: “{{FamilyId}}”, “FamilyName”: “{{FamilyName}}”, “ParentFamilyId”: “1”, “IsHidden”: “1” }, { “FamilyId”: “{{FamilyId}}”, “FamilyName”: “{{FamilyName}}”, “ParentFamilyId”: “1”, “IsHidden”: “0”, “Children”: [ { “FamilyId”: “{{FamilyId}}”, “FamilyName”: “{{FamilyName}}”, “ParentFamilyId”: “{{ParentFamilyId}}”, “IsHidden”: “0” } ] },… ]}
Comment:	The response contains a full list of the Families allowed for the respective Brand and category only. “ParentFamilyId”: “1” – means that for this family parent family is absent. “IsHidden”: “1” – means that this family is deprecated and should not be used for creating or updating the product.
Status:	200
Body:	{ “Data”: []}
Comment:	If you received an empty response, it means that for the given Brand and category there are no families. If you want to add a new family for the given Brand and category, please contact the taxonomy team.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Has not parameters: category_id | brand_id”}	In the request query mandatory parameters category_id or brand_id are absent.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not found by category_id | brand_id“}	User used absent {{CategoryId}} or {{SupplierID}}
501	{ “Code”: 501, “Error”: “Not Implemented”, “Message”: “Type: {{Type}} isn’t implemented”}	User input: incorrect value for query parameter “Type”.

2.2.5. Checking if FamilyId is mandatory for current SupplierID

Note. A “mandatory” FamilyID parameter is recommended and not strictly mandatory. Nevertheless, we strongly recommend that we add FamilyIDs that are identified as mandatory.
Request:

URL:	https://bo.icecat.biz/restful/v2/Brand/{{SupplierId}}?type=info&access_key={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{  “Data”: {    “IsFamilyMandatory”: false | true  }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not found BrandId”}	User input: absent {{SupplierId}}
501	{ “Code”: 501, “Error”: “Not Implemented”, “Message”: “Type: {{Type}} isn’t implemented”}	User input: incorrect value for query parameter “Type”

2.2.6. GET available SeriesId by product SupplierID and FamilyId

Request:

URL:	https://bo.icecat.biz/restful/v2/productseries?brand_id={{SupplierID}}&family_id ={{FamilyId}}&type=general&access_key={{SessionId}}
Method:	GET
Comment:	{{SupplierID}} – see 2.1. {{FamilyId}} – see 2.2.4.

Success response:

Status:	200
Body:	{ “Data”: [ { “SeriesId”: “{{SeriesId}}”, “SeriesName”: “{{SeriesName}}” },… ]}
Comment:	The response contains a full list of the Series allowed for current Brand and family only.
Status:	200
Body:	{ “Data”: []}
Comment:	If you received an empty response, it means that for the respective Brand and family there are no series created. If you want to add new series for the given Brand and family, please contact the taxonomy team.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Has not parameters: family_id | brand_id”}	Mandatory parameters are absent in the request query: family_id or brand_id.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not found by family_id | brand_id“}	User used absent {{FamilyId}} or {{SupplierID}}.
501	{ “Code”: 501, “Error”: “Not Implemented”, “Message”: “Type: {{Type}} isn’t implemented”}	User input: incorrect value for query parameter “Type”.

2.3. View “General” product record

Note: accounts with user role “brand” can view products only for the Brands they are assigned to.

Request:

URL:	https://bo.icecat.biz/restful/v3/Product/{{ProductId}}?AccessKey={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{ “Data”: { “ProductId”: {{ProductId}}, “Quality”: “SUPPLIER” | “ICECAT” | “NOEDITOR”, “ApprovedByBrand”: boolean, “CheckBySuperEditor”: boolean, “Publish”: { “AvailableValues”: [ “L”, “Y” ], “Checked”: “L” | “Y”, “Readonly”: boolean }, “ShowRemoveAllSpecs”: false, “PartCode”: “{{PartCode}}”, “IsDangerous”: boolean, “General”: { “Score”: false | {{Score}}, “DateAdded”: “DD-MM-YYYY”, “LastUpdate”: “DD-MM-YYYY”, “Readonly”: { “BrandPolicy”: boolean } }, “Brand”: { “BrandId”: “{{SupplierId}}”, “BrandName”: “{{BrandName}}” }, “Category”: { “CategoryId”: “{{CategoryId}}”, “CategoryName”: “{{CategoryName}}” }, “VirtualCategories”: [ { “VirtualCategoryId”: “{{VirtualCategoryId}}” }, … } ], “Family”: { “FamilyId”: “{{FamilyId}}”, “FamilyName”: “{{FamilyName}}” }, “Series”: { “SeriesId”: “{{SeriesId}}”, “SeriesName”: “{{SeriesName}}” }, “Owner”: { “UserId”: “{{UserId}}”, “UserLogin”: “{{UserLogin}}”, “UserGroup”: “supplier” }, “Warnings”: [], “AccessibleBy”: “AuthorizedResellers” | “SelectedResellers”, “ControlOwner”: true }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}.
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries viewing a product for a Brand it is not authorized to.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not Found Product”}	User input: absent {{ProductId}}.

2.4. Update “General” product record

Note: accounts with the user role “brand” can update “General” product content only for assigned Brands. Changing a product “PartCode” is not possible – if you need to change “PartCode” for a product , please contact the editor team.

Request:

URL:	https://bo.icecat.biz/restful/v3/Product/{{ProductId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{     “{{PropertyName}}”:{{PropertyValue}} }
Comment:	You can update only one property per single request. Allowed {{PropertyName}} for user role “brand”: “Brand”: “{{SupplierId}}” – see2.1. “Category”: “{{CategoryId}}} – see 2.2.1. “IsDangerous”: {{IsDangerous}} – (Boolean) true – means that the product has a dangerous property (in this case /restful/v3/ProductDescriptions parameter “disclaimer” is mandatory); false – means that the product hasn’t any dangerous properties. “Publish”: “{{Publish}}”– for accounts with user role “brand” only two values are allowed: “L”(Limited) – means the product will be allowed only for shop accounts which are authorized by the Brand, “Y”(Yes) –  ) – means the product will be allowed for all shop accounts. “VirtualCategories”: [“{{VirtualCategoryId}}”,…  ],} – see 2.2.3., for removing all virtual categories from a product one should send an empty array. “Family”: {{FamilyId}} – see 2.2.4. and 2.2.5. “SeriesId”: {{SeriesId}} – see 2.2.6. “ApprovedByBrand”:true | false – (Boolean) true – means the product was checked by the Brand user, in this case, the status of “Publish” will be changed from “No” to “Yes”. “AccessibleBy”:”AuthorizedResellers” | “SelectedResellers” – (AuthorizedResellers) means the product is allowed only for all Brand autorized resellers, (SelectedResellers) means the product is allowed only for selected Brand authorized resellers.

Success response:

Status:	200
Body:	{ “{{Updated PopertyName}}”: true, “Data”: { “{{ConnectedPropertyName}}”: “{{ChangedPropertyValue}}”,… }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries to lookup a product for a disallowed Brand.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not Found Product”}	User input: absent {{ProductId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Selected main category is not allowed to contain products. Please, select a category at the most detailed level”}	User input: a “root” CategoryId is used, not a leave.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Part number {{MPN}} is not unique. Another product with product id: {{ProductId}} was found”}	User tries to create a product with MPN and SupplierId which already exist in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Part number should be mapped, according to the product map rules”}	User tries to create a product with MPN and SupplierId for which already a mapping rule exists, and the mapped-to-product already exists in the Icecat database.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Not Found {{BrandId | CategoryId | UserId | FamilyId | SeriesId}}”}	User input: incorrect {{SupplierId}} , {{CategoryId}},{{UserId}},{{FamilyId}},{{SeriesId}}. {{FamilyId}} is not assigned to brand and category for this product. {{SeriesId}} is not  assigned to this {{FamilyId}}.

3. “Product model description” (product name) – create, read, update or delete

A product name is essential for a product. You normally see it in almost any product presentation. We are using this property to automatically generate product titles and short/long summary descriptions.

1. The accounts with user role “brand” can only work with allowed Languages (allowed languages or locales depend on the country in the user’s profile). For getting access to languages see 3.2.1.
2. If you want work with a full list of languages or locales, you should change your country to “International” on your user profile page.

Note: accounts with the user role “brand” can update or delete International (langId=0) product model descriptions. 

3.1. Get the full list “Product model description”

Request:

URL:	https://bo.icecat.biz/restful/ v2/productmodelname/{{ProductId}}?access_key ={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{ “product_model_name”: “{{International product model description}}”, “product_name”: [ { “name”: “{{International product model description}}”, “langid”: “0” } ], “product_model_name_local”: [], “readOnlyProductName”: true}
Comment:	Response for product without local product model description.
Body:	{ “product_model_name”: “{{InternationalProductModelDescription}}”, “product_name”: { “0”: { “name”: “{{InternationalProductModelDescription}}”, “langid”: “0” }, “{{langid}}”: { “product_name_id”: “{{product_name_id}}”, “product_id”: “{{product_id}}”, “name”: “{{LocalProductModelDescription}}”, “langid”: “{{langid}}”, “updated”: “YYYY-MM-DD HH:MM:SS” } }, “product_model_name_local”: [ { “product_name_id”: “{{product_name_id}}”, “product_id”: “{{product_id}}”, “name”: “{{LocalProductModelDescription}}”, “langid”: “{{langid}}”, “updated”: “YYYY-MM-DD HH:MM:SS” } ], “readOnlyProductName”: true}
Comment:	Response for a product with a local product model description.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries to work with a product for a disallowed Brand.

3.2. Create localized “Product model description”

Request:

URL:	https://bo.icecat.biz/restful/v2/productmodelname/{{ProductId}}? lang_id={{langId}}&access_key={{SessionId}}
Method:	POST
Body:	{ “name”: “{{name}}”}
Comment:	{{langId}} – Look at the p.3.2.1. {{name}} – Local “Product model description”. For this value will be applied trimming leading and ending “space” symbols

Success response:

Status:	200
Body:	{ “message”: “Created”, “id”: {{productId}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries to work on a product for a Brand or language it has no authorization.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product name already exists”}	“Product model description” already exists for the given language.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is not found”}	User uses a language which is absent in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product name shouldn’t be empty.”}	You shouldn’t send empty {{name}} for removing current “Product model description”. For removing see 3.4.
400	{  “Code”: 400,  “Error”: “Bad Request”,  “Message”: “Product name should be less than 3000 characters.”}	{{name}} should have a length of up to 3000 characters.

3.2.1 GET available languages for a user (user role “brand”) by user session

Note: accounts with user role “brand” can get the full list of languages (use query parameter “type”=”all”), but any request with disallowed languages is not allowed and will return a 403 response.

Request:

URL:	https://bo.icecat.biz/restful/v2/language?access_key={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	[ { “langid”: “25”, “code”: “ukrainian”, “short_code”: “UK”, “published”: “Y”, “backup_langid”: “8”, “separators”: “,”, “measurement”: “metric” },…]
Comment:	The response contains the full list of languages allowed for your user account.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

3.3. Update localized “Product model description”

Request:

URL:	https://bo.icecat.biz/restful/v2/productmodelname/{{ProductId}}? lang_id={{langId}}&access_key={{SessionId}}
Method:	PATCH
Body:	{ “name”: “{{name}}”}
Comment:	{{langId}} – see 3.2.1. {{name}} – Local “Product model description”. For this value will be applied trimming leading and ending “space” symbols.

Success response:

Status:	200
Body:	{ “product_model_name”: “{{InternationalProductModelDescription}}”, “product_name”: { “0”: { “name”: “{{InternationalProductModelDescription}}”, “langid”: “0” }, “{{langid}}”: { “product_name_id”: “{{product_name_id}}”, “product_id”: “{{product_id}}”, “name”: “{{LocalProductModelDescription}}”, “langid”: “{{langid}}”, “updated”: “YYYY-MM-DD HH:MM:SS” } }, “product_model_name_local”: [ { “product_name_id”: “{{product_name_id}}”, “product_id”: “{{product_id}}”, “name”: “{{LocalProductModelDescription}}”, “langid”: “{{langid}}”, “updated”: “YYYY-MM-DD HH:MM:SS” } ], “readOnlyProductName”: true}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries working with a product of a Brand or language it is not authorized to.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is not found”}	User used a language which is absent in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product name shouldn’t be empty.”}	You shouldn’t send an empty {{name}} for removing current “Product model description”. For removal see 3.4.
400	{  “Code”: 400,  “Error”: “Bad Request”,  “Message”: “Product name should be less than 3000 characters.”}	The {{name}} should have a length of up to 3000 characters.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Brand user cannot change INT product name”}	Accounts with user role “brand” can’t update or delete the International (langId=0) product model description.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product name is not found”}	“Product model description” for current “langid” is absent.

3.4. Delete localized “Product model description”

Request:

URL:	https://bo.icecat.biz/restful/v2/productmodelname/{{ProductId}}? lang_id={{langId}}&access_key={{SessionId}}
Method:	DELETE
Comment:	–

Success response:

Status:	200
Body:	{ “message”: “Deleted”, “id”: {{productId}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input:incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	The user tries to work with a product for a Brand or language it’s not authorized to.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is not found”}	User uses a language which is absent in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product name is not found”}	“Product model description” for current “langid” is absent.

4. “Release date” and  “End of life date” – create, read, update or delete

You can add the Release Date of a product  – the date when this product is expected to be released to the market. That can be a global or country-specific (a release date per country). Shops which are not authorized by a brand can only access product data after the release date is passed. Shops  authorized by the brand can access product data prior to Release date..

End of life date – the date when this product is End of Life.

Swagger schema – https://api.icecat.biz (ProductLifeCicle)

Accounts with user role “brand” can work only with an allowed Country (the allowed country as displayed in your user profile). See 4.2.1.

 If you want work with the full list of countries, you should change your country to “International” on your user profile page.

4.1. Get the full list of Release and End of life dates

Note: accounts with user role “brand” can read, create, update or delete “Release and End of life date” only for allowed countries.

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductLifecycles?ProductId={{ProductId}}&AccessKey ={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{ “Data”: [ { “LifeCycleId”: {{LifeCycleId}}, “ProductId”: {{ProductId}}, “CountryId”: {{CountryId}}, “ReleaseDate”: “{{DD-MM-YYYY}}”, “EndOfLifeDate”: “{{DD-MM-YYYY}}” },… ]}
Comment:	The response contains the full list of allowed “Release and End of life” dates
Status:	204
Comment:	If you received an empty response, it means that for the given product Release and End of life dates are absent.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied.”}	User tries to work on a product of a Brand it is not authorized to.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ProductId is unknown.”}	User uses a {{ProductId}} which is absent in the Icecat database.

4.2. Create “Release date” and “End of life date”

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductLifecycles?AccessKey={{SessionId}}
Method:	POST
Body:	{ “ProductId”: {{ProductId}}, “CountryId”: {{CountryId}}, “ReleaseDate”: “{{DD-MM-YYYY}}”, “EndOfLifeDate”: “{{DD-MM-YYYY}}”}
Comment:	{{CountryId}} – see 4.2.1. “ReleaseDate” and “EndOfLifeDate” – can be created by one request or by separate requests.

Success response:

Status:	200
Body:	{ “Data”: { “LifeCycleId”: {{LifeCycleId}}, “ProductId”: {{ProductId}}, “CountryId”: {{CountryId}}, “ReleaseDate”: “{{DD-MM-YYYY}}”, “EndOfLifeDate”: “{{DD-MM-YYYY}}” }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. “}	User tries working on a product of a Brand or language for which it is not authorized.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ReleaseDate | EndOfLifeDate already exists.”}	“Release or End of life dates” already exist for the given language.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ReleaseDate should be less than EndOfLifeDate.”}	User enters a ReleaseDate later than EndOfLifeDate
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ProductId is unknown.”}	User uses a {{ProductId}} which is absent in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “CountryId is unknown.”}	User uses a {{CountryId}} which is absent in the Icecat database.

4.2.1. GET full list of CountryId

Request:

URL:	https://bo.icecat.biz/restful/v3/Countries?AccessKey={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{ “Data”: [ { “Code”: “AF”, “Name”: “Afghanistan”, “CountryId”: “43” }, { “Code”: “AX”, “Name”: “Aland Islands”, “CountryId”: “237” }, … ]}
Comment:	Response contains the full list of countries.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

4.3. Update “Release date” and “End of life date”

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductLifecycles/{{LifeCycleId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{ “ReleaseDate”: “{{DD-MM-YYYY}}”, “EndOfLifeDate”: “{{DD-MM-YYYY}}”}
Comment:	{{LifeCycleId}} – see 4.1. or 4.2. “ReleaseDate” and “EndOfLifeDate” – can be updated by one request or by separate requests.

Success response:

Status:	200
Body:	{ “Data”: { “LifeCycleId”: {{LifeCycleId}}, “ProductId”: {{ProductId}}, “CountryId”: {{CountryId}}, “ReleaseDate”: “{{DD-MM-YYYY}}”, “EndOfLifeDate”: “{{DD-MM-YYYY}}” }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}.
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. “}	User tries working on a product of a Brand or in a language it is not authorized to.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ReleaseDate should be less than EndOfLifeDate.”}	User sets the ReleaseDate later than EndOfLifeDate.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Life cycle is not found.”}	User uses {{LifeCycleId}} which is absent in the Icecat database.

4.4. Delete “Release date” and “End of life date”

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductLifecycles/{{LifeCycleId}}?AccessKey={{SessionId}}
Method:	DELETE
Body:	{ “DateNames”: [ “ReleaseDate”, “EndOfLifeDate” ]}
Comment:	{{LifeCycleId}} – see 4.1., 4.2. or 4.3. “ReleaseDate” and “EndOfLifeDate” – can be deleted by a single request or by separate requests.

Success response:

Status:	200
Body:	{ “Data”: { “LifeCycleId”: {{LifeCycleId}}, “ProductId”: {{ProductId}}, “CountryId”: {{CountryId}}, “ReleaseDate”: “”, “EndOfLifeDate”: “” }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. “}	User tries to work on a product for a Brand or language it is not authorized to.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Life cycle is not found.”}	User uses a {{LifeCycleId}} which is absent in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ReleaseDate should be less than EndOfLifeDate.”}	User sets ReleaseDate later than than EndOfLifeDate
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Requested life cycle does not have ReleaseDate.| EndOfLifeDate “}	User tries to delete “ReleaseDate” or “EndOfLifeDate” which are already absent in the Icecat database.

5. “Product personalized access” – view, update or delete for authorized resellers

As a brand user, you can allow product access to all shops (resellers) or only to a special group of users. These are called assigned to (authorized by) the brand. 
At a product level access settings, have several options: 

• Publish=Yes opens product to all users. Users can access this product on Icecat portals, through XML/JSON, Live and other data channels.

• Publish=Limited: product data is accessible by all authorized resellers – product is only accessible to all shops which are already assigned to the Brand.

• Publish=No. Data is not accessible to any “shop” user.

1. The accounts with user role “brand” can restrict access to products to “shop” users selected from a list of authorized resellers.
2. If the shop user is absent from the list of authorized resellers for your Brand, please contact your Icecat account manager to add the user to the authorized resellers list.
3. Only a product with properties: “Publish”: {“Checked”: “L”} and “AccessibleBy”: SelectedResellers” can be configured for such restricted reseller access.
4. For creating a product with property “Publish”: {“Checked”: “L”} see 2.2.
5. For checking (reading) these properties in a product see 2.3.
6. For changing these properties in a product see 2.4. to set {“Publish”:”L”} and {“AccessibleBy”:”SelectedResellers”}.

Note. Be careful, if you set the property {“AccessibleBy”:”SelectedResellers”} for a product and do not authorize any user it  will be fully restricted for all users as if you have set Publish=No.

5.1. Read the list of selected resellers for a product

Request:

URL:	https://bo.icecat.biz/restful/v2/ProductPersonalizedAccess/{{ProductId}}?access_key={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	{ “Data”: [ { “UserId”: {{SelectedResellerUserId}}, “UserLogin”: “{{UserLogin}}”, “CompanyName”: “{{CompanyName}}” }, … ]}
Comment:	Response contains the list of selected resellers for the given product.
Status:	200
Body:	{ “Data”: []}
Comment:	If the authorized reseller wasn’t selected for the current product.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

5.2. Add users to the list of selected resellers for the given product

Request:

URL:	https://bo.icecat.biz/restful/v2/ProductPersonalizedAccess/{{ProductId}}?access_key={{SessionId}}
Method:	PATCH
Body:	{ “UserId”: [ “{{AssignedResellerUserId}}”, … ]}
Comment:	{{AssignedResselerUserId}} – Look at the p.5.2.1.

Success response:

Status:	200
Body:	{“Message”:”Added”}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “User(s) already exist in access list”}	Such {{AssignedResselerUserId} is already authorized for the product.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “User(s) is not assigned brand”}	The given AssignedResselerUserId does not belong to the list of authorized Brand resellers.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Brand for product is not found”}	The given product is absent in the Icecat database.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “User(s) is not found”}	The given authorized reseller is absent in the Icecat database.

5.2.1. Read full list of authorized resellers for a given Brand

Note. If the necessary “shop” user is absent from the list of the authorized resellers for the current Brand, please contact your Icecat account manager to add the respective user to the list of authorized resellers.

Request:

URL:	https://bo.icecat.biz/restful/v3/Users?Query=&Type=Assigned&BrandId={{SupplierId}}&AccessKey={{SessionId}}
Method:	GET
Comment:	{{SupplierId}} – see 2.1. (full list) or 2.3. (for the given product)

Success response:

Status:	200
Body:	{ “Data”: [ { “UserId”: {{AssignedResellerUserId}}, “UserLogin”: “{{UserLogin}}”, “CompanyName”: “{{CompanyName}}” }, … ]}
Comment:	Response contains the full list of authorized resellers for the given product.
Status:	200
Body:	{ “Data”: []}
Comment:	If there are no authorized resellers for the given Brand.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

5.3. Delete users from list of selected resellers for a given product

Request:

URL:	https://bo.icecat.biz/restful/v2/ProductPersonalizedAccess/{{ProductId}}?access_key={{SessionId}}
Method:	DELETE
Body:	{ “UserId”: [ “{{SelectedResellerUserId}}”, … ]}
Comment:	{{SelectedResellerUserId}} – Look at the p.5.1.

Success response:

Status:	200
Body:	{“Message”:”Deleted”}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “User(s) is not found in access list”}	Such {{AssignedResselerUserId} is absent for the product.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “User(s) is not assigned brand”}	The given {{AssignedResselerUserId}} does not belong to the authorized Brand resellers list.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Brand for product is not found”}	The given product is absent in the Icecat database.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “User(s) is not found”}	The authorized reseller is absent from the Icecat database.

6. “GTIN” – view, create, update, or delete a product

One of the main identifiers for a product is the GTIN. It is supported by Icecat, so you can manipulate product GTINs through this Push-API. Each product can have multiple GTINs. 

Icecat supports GTIN 8-12-13-14 lengths.

All GTIN types are are automatically converted to EAN-13, and an EAN-14 with a leading “0” automatically will be converted to EAN-13 by removing the leading 0.

A GTIN is a unique value across all products in the database.

Note. If your GTIN belongs to another product which is restricted for your user account, please contact the Editor team for resolving this GTIN conflict.

6.1. Read product “GTINs”

Request:

URL:	https://bo.icecat.biz/rest/productgtin?filter={%22product_id%22:{{ProductId}}}&access_key={{SessionId}}
Method:	GET
Comment:	–

Success response:

Status:	200
Body:	[ { “ean_id”: “{{ean_id}}”, “product_id”: “{{ProductId}}”, “ean_code”: “{{EAN}}”, “updated”: “{{YYYY-MM-DD HH:MM:SS}}”, “data_source_id”: “{{data_source_id}}”, “distributor_id”: “{{distributor_id}}”, “is_exported”: true | false, “editor_user_id”: “{{editor_user_id}}”, “variant_id”: “{{variant_id}}”, “country”: “{{CountryName}}”, “source_name”: “{{UserLogin}}” }, …]
Comment:	Response contains a full list of GTINs for the product requested. If property “is_exported”: false, it means this EAN is not validated by any editor or brand account. For confirming EAN use p.6.3.
Status:	200
Body:	[]
Comment:	If in the given product GTINs are absent.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

6.2. Create product “GTIN”

Request:

URL:	https://bo.icecat.biz/rest/productgtin/{{ProductId}}?access_key={{SessionId}}
Method:	POST
Body:	{“barcode”:”{{barcode}}”}
Comment:	–

Success response:

Status:	200
Body:	{ “message”: “Created”, “id”: “{{ean_id}}”}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Icecat GTIN supports 8-12-13-14 length”}	Icecat supports only GTIN 8-12-13-14 lengths
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid GTIN code {{GTIN}}, checksum failed.”}	User input: incorrect GTIN. Please validate your GTIN first: https://www.free-barcode-generator.net
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “GTIN code {{GTIN}} already belongs to product (part number is {{MPN}}) EanId: {{ean_id}}”}	Your GTIN already belongs to another product.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Requested product is not present in Icecat database.”}	The product is absent from the Icecat database.

6.3. Update product “GTIN”

Request:

URL:	https://bo.icecat.biz/rest/productgtin/{{ean_id}}?access_key={{SessionId}}
Method:	PATCH
Body:	{“is_exported”:true}
Comment:	{{ean_id}} – Look at the p.6.1.

Success response:

Status:	200
Body:	{ “ean_id”: {{ean_id}}, “product_id”: {{product_id}}, “ean_code”: “{{EAN}}”, “updated”: “{{YYYY-MM-DD HH:MM:SS}}”, “data_source_id”: {{data_source_id}}, “distributor_id”: {{distributor_id}}, “is_exported”: 1, “editor_user_id”: {{editor_user_id}}, “variant_id”: {{variant_id}}}
Comment:	–
Status:	204
Comment:	If {{ean_id}} is absent from the Icecat database.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Failed update. is_exported now is true.”}	The user tries to remove the confirmation from the GTIN ({“is_exported”:false}) or if the given GTIN is already confirmed.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid GTIN code {{GTIN}}, checksum failed.”}	The user inputs an incorrect GTIN. Please, validate your GTIN: https://www.free-barcode-generator.net
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “GTIN code {{GTIN}} already belongs to product (part number is {{MPN}}) EanId: {{ean_id}}”}	Your GTIN already belongs to another product.
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “Requested product is not present in Icecat database.”}	The given product is absent from Icecat’s database.

6.4. Delete product “GTIN”

Request:

URL:	https://bo.icecat.biz/rest/productgtin/{{ean_id}}?access_key={{SessionId}}
Method:	DELETE
Comment:	{{ean_id}} – see 6.1., 6.2. or 6.3. depending on your user scenario.

Success response:

Status:	200
Body:	{ “message”: “Deleted”, “id”: “{{ean_id}}”}
Comment:	–
Status:	204
Comment:	If such {{ean_id}} is absent from the Icecat data base.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}

7. Product features (Specs) – view, create, update or delete

One of the main content elements in every product is specifications. You can add all necessary specifications to every product. In our system we have more than 27K different specs defined. Every category has a special set attached to it, which we call a product taxonomy. We are sure that you can find in the list all necessary specs to describe your product. If you miss spec definitions, please contact the taxonomy team.

All product specifications are divided in two levels: “black” and “gray”. The “black” specifications are checked and approved by the taxonomy team. The “gray” specifications are deprecated or not approved for adding. Therefore, we do not recommend filling “gray” specs in your product.

The product specifications are divided over 14 input types: 

• “Text area” – allowing any string of symbols (new line symbols also);
• “Text line” – allowing any string of symbols (except new line symbols);
• “Yes/No” – allowed symbols are “Y”, “N”, “-“ (means “Undescribed”);
• “Yes/No/Optional” – allowed symbols are “Y”, “N”, “O”, “-“ (means “Undescribed”);
• “Dropdown” – allowed only one option from a list of restricted values for this specification or “-“. If your needed value is absent from a restricted values list: see 9.;
• “Numerical” (#) – allowed any floating and integer values corresponding to a pattern ‘((\-?[1-9]\d*)|(\-?\d+[.]\d*[1-9])|(0))’ or “-“;
• “Range” (# – #) – allowed only floating and integer values in the specified combination (“Numerical” – “Numerical”) or “-”
• “Ratio” (#/#) – allowed only floating and integer values in the specified combination (“Numerical”/“Numerical”) or “-”
• “Contrast ratio” (#:#) – allowed only floating and integer values in the specified combination (“Numerical”:“Numerical”) or “-”
• “3 dimensions” (# x # x #) – allowed only floating and integer values in the specified combination (“Numerical” x “Numerical” x “Numerical”) or “-”
• “2 dimensions” (# x #) – allowed only floating and integer values in the specified combination (“Numerical” x “Numerical”) or “-”
• “Multi feature” – allowed multiple values from a list of restricted values for this spec (in any combination) or “-“. Values for this spec are added with separator: “,”. Example: “value1,value3,value10”. If your value is absent from the respective list of restricted values, contact the taxonomy team;
• “Date(YYYY-MM-DD)” – allowed is only one date value
• “Alphanumerical code” – allowed are any string of symbols (except new line symbols).

The product specifications can accept localized values: “Text area” and “Text line” with “measure_id”=29 can accept localized values. All other features accept only values for the “International” (standardized) locale (lang_id=0).

The accounts with user role “brand” can work only with allowed Languages and “International” (lang_id=0) (allowed languages depends on the country setting in the user profile). For getting multiple allowed languages see 4.2.1.

If you want to work with the full list of languages, you should change your country to “International” on your user profile page.

The allowed specs for a product depend on the product’s category. If your product feature is absent from your selected category, please contact the taxonomy team for adding a spec to a category

7.1. Read all International product specs

Request:

URL:	https://bo.icecat.biz/rest/productfeatures/{{ProductId}}?showFeature=black&access_key={{SessionId}}
Method:	GET
Comment:	The response contains the full list the black product specs if showFeature=black. If showFeature is absent from the query – then the full list of black and gray features will be returned. showFeature=grayFill – filled gray features will be displayed (which have the property “product_feature.value” filled) showFeature=grayEmpty – empty gray features will be displayed

Success response:

Status:	200
Body:	[{   //empty feature “category_feature_group_id”: “{{category_feature_group_id}}”, “group_value”: “{{group_value}}”, “category_feature_id”: “{{category_feature_id}}”, “cf_no”: “{{cf_no}}”, “cfg_no”: “{{cfg_no}}”, “order_number”: “{{order_number}}”, “cf_searchable”: “0” | “1”, “restricted_search_values”: “{{restricted_search_values}}” | “” | null, “use_dropdown_input”: “Y” | “N” | “”, “mandatory”: “0” | “1”, “is_hidden”: “0” | “1”, “cf_value_sorting”: “0” | “1”, “avoid_auto_ordering”: “0” | “1”, “participate_in_title”: “0” | “1”, “feature_id”: “{{feature_id}}”, “sid”: “{{sid}}”, “tid”: “{{tid}}”, “measure_id”: “{{measure_id}} | “”, “type”: “{{type}}”, “class”: “0” | “1”, “limit_direction”: “0” | “1”, “f_searchable”: “0” | “1”, “restricted_values”: “{{restricted_values}}” | “”, “f_value_sorting”: “0” | “1”, “highlight_supplier_id”: “0” | “1”, “num_products”: “{{num_products}}”, “brand_specific”: “0” | “1”, “value”: “{{feature_name}}”, “langid”: {{langid}}, “system_of_measurement”: “metric” | “imperial”, “sign”: “{{sign}}” | “”, “measure_sign”: “{{measure_sign}}” | “”, “pattern”: “{{pattern}}” | “”, “patternName”: “{{patternName}}”, }, {  //filled feature “category_feature_group_id”: “{{category_feature_group_id}}”, “group_value”: “{{group_value}}”, “category_feature_id”: “{{category_feature_id}}”, “cf_no”: “{{cf_no}}”, “cfg_no”: “{{cfg_no}}”, “order_number”: “{{order_number}}”, “cf_searchable”: “0” | “1”, “restricted_search_values”: “{{restricted_search_values}}” | “” | null, “use_dropdown_input”: “Y” | “N” | “”, “mandatory”: “0” | “1”, “is_hidden”: “0” | “1”, “cf_value_sorting”: “0” | “1”, “avoid_auto_ordering”: “0” | “1”, “participate_in_title”: “0” | “1”, “feature_id”: “{{feature_id}}”, “sid”: “{{sid}}”, “tid”: “{{tid}}”, “measure_id”: “{{measure_id}} | “”, “type”: “{{type}}”, “class”: “0” | “1”, “limit_direction”: “0” | “1”, “f_searchable”: “0” | “1”, “restricted_values”: “{{restricted_values}}” | “”, “f_value_sorting”: “0” | “1”, “highlight_supplier_id”: “0” | “1”, “num_products”: “{{num_products}}”, “brand_specific”: “0” | “1”, “value”: “{{feature_name}}”, “langid”: {{langid}}, “system_of_measurement”: “metric” | “imperial”, “sign”: “{{sign}}” | “”, “measure_sign”: “{{measure_sign}}” | “”, “pattern”: “{{pattern}}” | “”, “patternName”: “{{patternName}}”, “product_feature”: { “product_feature_id”: “{{product_feature_id}}”, “value”: “{{feature_value}}”, “category_feature_id”: “{{category_feature_id}}”, “updated”: “{{YYYY-MM-DD HH:MM:SS}}”, “editor_user_id”: “{{editor_user_id}}” }, “product_counter”: { “category_feature_id”: {{category_feature_id}}, “count”: {{count}}, “languages_ids”: [ {{language_id}}, {{language_id}} ] } }, …]
Comment:	Properties: “product_feature” and “product_counter” exist only for filled specs and can be used to request local spec values – see 7.2. “restricted_search_values” – this field contains a full list of allowed values for the current feature. The value separator is (\n). A value from this list should be used only if the current feature has the parameter “use_dropdown_input”:”Y”. “use_dropdown_input” – if this field value is “Y” it means that this feature is of the type “Dropdown” even if the field “type” contains another feature type. “mandatory”:”1” – means that this feature highly recommended for filling. “is_hidden”:”1” – means that this feature belongs to the gray features list. “participate_in_title”:”1” – means that the feature value will be used for creating a local product title if in the given product local product name for the given language is not filled. “type” – contains the product feature type “restricted_values” – this field contains a full list of allowed values for the current feature. The value separator is (\n). A value from this list should only be used if the current feature has the parameter “use_dropdown_input”:”N” or “” and feature type: “Dropdown”, “Yes/No”, “Yes/No/Optional”, “Multi feature” . “value” – contains product feature name. “product_feature.value” – contains international feature value. “product_counter. languages_ids[]” – contains the list of language ids for getting local feature values category_feature_id – contains identifier relation between feature and category
Status:	200
Body:	[]
Comment:	If any feature is not connected to the current product category.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Have not this product_id {{product_id}}”}	Given product is absent from the Icecat database

7.2. Read local product feature value

Request:

URL:	https://bo.icecat.biz/rest/productfeatures/{{ProductId}}?lang_id={{language_id}}&category_feature_id={{category_feature_id}}&access_key={{SessionId}}
Method:	GET
Comment:	Response contains a full or filtered list of product feature values. lang_id={{language_id}} – optional parameter that can be used for filtering the “product_features_local” list. If this parameter is absent or equals “0”, the response will contain a full list of the filled “product_features_local” values for current “category_feature_id”. Exact list {{language_id}} for filled features value can be taken from the response. See 7.1. category_feature_id – see 7.1 product_feature.category_feature_id

Success response:

Status:	200
Body:	{ “product_feature”: { “product_feature_id”: “{{product_feature_id}}”, “value”: “{{international_feature_value}}”, “category_feature_id”: “{{category_feature_id}}”, “updated”: “{{YYYY-MM-DD HH:MM:SS}}”, “editor_user_id”: “{{editor_user_id}}” }, “product_features_local”: [ { “product_feature_local_id”: “{{product_feature_local_id}}”, “value”: “{{local_feature_value}}”, “category_feature_id”: “{{category_feature_id}}”, “langid”: “{{langid}}”, “updated”: “{{YYYY-MM-DD HH:MM:SS}}”, “editor_user_id”: “{{editor_user_id}}” }, …. ]}
Comment:	“product_counter. languages_ids[]” – contains the list of languages ids for getting local feature values category_feature_id – contains the identifier relation between feature and category.
Status:	200
Body:	[]
Comment:	If a feature is not connected to the given product category.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Have not this product_id {{product_id}}”}	The given product is absent from the Icecat database.

7.3. Create product feature value

Request:

URL:	https://bo.icecat.biz/rest/productfeatures/{{ProductId}}?access_key={{SessionId}}&lang_id={{lang_id}}
Method:	POST
Body:	{“category_feature_id”:”{{category_feature_id}}”,“value”:”{{value}}”}
Comment:	1. The product features can accept localized values. Only features types “Text area” and “Text line” with “measure_id”=29 can accept localized values. All other features accept only “International” features (lang_id=0).If lang_id is not set, lang_id=0 by default 2. category_feature_id – Look at the response p.7.1 product_feature.category_feature_id 3. For setting values for “Multi Feature” type should separate values by the symbol “,” “value”:”value1,value2″

Success response:

Status:	200
Body:	{ “message”: “Created”, “id”: “{{id}}”}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input is incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. “}	User tries working with a product for a not allowed Brand or language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Feature already exists.”}	Feature already exists
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product can not contain requested feature.”}	User sends incorrect {{category_feature_id}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: ” Please, correct the red highlighted fields. Feature {{feature_name}} is `{{type}}` and have to has ` ` format”}	User sends incorrect type of feature value
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “We have not this value in available values dropdown for FeatureId: {{feature_id}}”}	User sets value that does not exist in the list of restricted values for dropdown or multi feature

7.4. Update product feature value (INT and local)

Request:

URL:	For int value: https://bo.icecat.biz/rest/productfeatures/{{ProductId}}? lang_id=0&access_key={{SessionId}}&product_feature_id={{product_feature_id}}
URL:	For local value: https://bo.icecat.biz/rest/productfeatures/{{ProductId}}? lang_id={{langId}}&access_key={{SessionId}}&product_feature_id={{product_feature_local_id}}
Method:	PATCH
Body:	{“value”: “{{value}}”}
Comment:	For updating int feature value. {{product_feature_id}} – Look at the response p.7.1 or p.7.2 product_feature.product_feature_idFor updating local feature value.{{product_feature_local_id}} – Look at the response p.7.2 product_features_local.product_feature_local_idFor updating values for “Multi Feature” type should separate values by the symbol “,” “value”:”value1,value2″

Success response:

Status:	200
Body:	{ “update_result”: { “message”: “Update”, “id”: {{id}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries working with a product for a not allowed Brand or language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Parameter value must be not empty string”}	You shouldn’t send an empty {{value}} for removing the current “Product feature value”. For removing see 7.5.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is not found”}	User sets langid which is absent in the Icecat database
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Feature does not exist in the product.”}	User sets incorrect or not existing {{product_feature_id}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “We have not this value in available values dropdown for FeatureId: {{feature_id}}”}	User sets value that does not exist in the list of restricted values for dropdown or multi feature
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Feature does not exist in the product.”}	Feature has no value for specified lang_id or feature value does not exist

7.5. Delete product feature value (INT and local)

Request:

URL:	For int value:https://bo.icecat.biz/rest/productfeatures/{{ProductId}}? lang_id={{langId}}&access_key={{SessionId}}&feature_id={{product_feature_id}}
URL:	For local value: https://bo.icecat.biz/rest/productfeatures/{{ProductId}}? lang_id={{langId}}&access_key={{SessionId}}&feature_id={{product_feature_local_id}}
Method:	DELETE
Comment:	For deleting int feature value. {{product_feature_id}} – see 7.2. product_feature.product_feature_id for deleting local feature value. {{product_feature_local_id}} – see 8.2 product_features_local.product_feature_local_id

Success response:

Status:	200
Body:	{ “message”: “Deleted”, “id”: “75279388”}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries working with a product for a not allowed Brand or language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is not found”}	User sets langid which is absent from the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Nothing to delete.”}	Feature has no value for specified lang_id or feature value does not exist

8. Add new value to restricted values list

The accounts with user role “brand” can add new values to the restricted values list for features with input types “Dropdown” and “Multi features”. Please, use this method only for adding values for input types “Dropdown” and “Multi feature”.

Note. a new value will not be added immediately. Please, contact the taxonomy team for adding your value.

Request:

URL:	https://bo.icecat.biz/restful/v2/featurenewvalues/{{ProductId}}?access_key={{SessionId}}
Method:	POST
Body:	{“category_feature_id”:”{{category_feature_id}}”,“value”:”{{value}}”,“info_url”:”{{info_url}}”}
Comment:	1. category_feature_id – see 7.1 product_feature.category_feature_id2. It is not recommended to use a “,” (comma) in value3. Please, specify the URL where such feature value can be found.

Success response:

Status:	201
Body:	{ “message”: “Created”, “id”: “{{id}}”}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Wrong category_feature_id”}	User set incorrect {{category_feature_id}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “This value has been already requested earlier”}	Such a request has been sent earlier.

9. Мultimedia objects (MMO) – view, create or update

For a better understanding of a product rich media can be added to product data-sheets: videos, 360 views, different PDFs – manuals, leaflets, energy labels, a Product Story etc. In our system all this information can be viewed, added or updated via one multimedia API.

Swagger schema – https://api.icecat.biz (Multimedia)

The accounts with user role “brand” can not delete multimedia objects. Use {{Visible}}: false parameter to deactivate it instead. See 9.3.

Each type of multimedia object can accept only certain content types:

1. leaflet – pdf;
2. manual pdf – pdf;
3. other digital assets – pdf, jpg, jpeg, png;
4. EU Product Fiche – pdf, jpg, jpeg, png for any language except INT;
5. EU Energy Label – pdf, jpg, jpeg, png (only for INT language);
6. UK Energy Label – pdf, jpg, jpeg, png (only for EN language);
7. Safety Data Sheet – pdf;
8. Size Chart – pdf, jpg, jpeg, png;
9. Video/mp4 – flv, mp4, mpg, mpeg, 3gp, webm, ogg, ogv;
10. 360 – batch of images in jpg, jpeg, png. The batch must contain 10 to 360 different links to images. From 10 to 36 links is recommended.
11. Product Story – zip file;
12. ProductStory2.0 – txt file (with valid html content);
13. Repairability index overview – pdf, jpg, jpeg, png.

Note. It is not recommended to send pdf objects larger than 50MB and video objects larger than 350MB.

9.1. View multimedia objects (MMO)

Request:

URL:	https://bo.icecat.biz/restful/v3/multimedia/{{ProductId}}?AccessKey={{SessionId}}
Method:	GET

Success response:

Status:	200
Body:	[    {        “Id”: {{Id}},        “ContentType”: {{ContentType}},        “DataSourceId”: {{DataSourceId}},        “ExpiryDate”: “{{YYYY-MM-DD}}“,        “IsPrivate”: true/false,        “KeepAsUrl”: true/false,        “LangId”: {{lang_id}},        “LinkOrigin”: “{{LinkOrigin}}”,        “Link”: “{{Link}}”,        “Md5Origin”: “{{MD5Origin}}”,        “PreviewLink”: “{{PreviewLink}}”,        “PreviewHeight”: {{PreviewHeight}},        “PreviewSize”: {{PreviewSize}},        “PreviewWidth”: {{PreviewWidth}},        “ConvertedLink”: “{{ConvertedLink}}”,        “ConvertedMimeType”: “” | “video/mp4”,        “ConvertedSize”: {{ConvertedSize}},        “ShortDescr”: “{{ShortDescr}}”,        “Size”: {{Size}},        “ThumbLink”: “{{ThumbLink}}”,        “Type”: “{{Type}}”,        “Uuid”: “{{Uuid}}”,        “Visible”: true/false,        “Updated”: “{{YYYY-MM-DD HH:MM:SS}}“,        “Expired”: true/false, “EnergyLabellingLink”: “{{EnergyLabellingLink}}”, “IsNewEnergyLabelling”: true/false,        “ImagesBatch”: [           {             “Link”: “string”,             “Order”: 0,             “Link400”: “string”,             “Link1000”: “string”,             “ContentType”: “string”,             “OriginalLink”: “string”,             “Link2000”: “string”,             “Md5Origin”: “string”      }    ]    },…]
Comment:	1. {{ConvertedMimeType}} – Content type of converted video. If MMO is video2. {{ImageBatch}} – List of links for generating 360 objects. Will be shown only if the object’s type is ‘360’.
Status:	204
Comment:	No content

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Have not this product_id {{product_id}}”}	The given product is not in the Icecat database.

9.2. Create multimedia objects (MMO)

Request:

URL:	https://bo.icecat.biz/restful/v3/multimedia/{{ProductId}}?AccessKey={{SessionId}}
Method:	POST
Body:	{  “LangId”: {{lang_id}},  “ShortDescr”: {{ShortDescr}},  “IsPrivate”: true | false,  “Visible”: true | false,  “Link”: {{Link}},  “KeepAsUrl”: true | false,  “Type”: {{Type}},  “ExpiryDate”: “{{YYYY-MM-DD}}“,  “EnergyLabellingLink”: “{{EnergyLabellingLink}}”, “IsNewEnergyLabelling”: true | false, “ImagesBatch”: [    {      “Link”: {{Link}},      “Order”: {{Order}}    }  ]}
Comment:	1. {{ImageBatch}} – List of links for generating 360 objects. Should be set only if the object’s Type is ‘360’ 2. {{ShortDescr}} – the parameter will be accepted only for media types: pdf, video and 360. (Also mandatory for these types) 3. {{KeepAsUrl}}:true parameter allowed only for types video, Safety Data Sheet and Size Chart. 4. {{IsNewEnergyLabelling}}:true parameter allowed only for types EU Energy Label, UK Energy Label 5. {{EnergyLabellingLink}} – parameter allowed only for types EU Energy Label, UK Energy Label

Success response:

Status:	201
Body:	{ “Code”: 201, “Message”: “Created”, “Uuid”: {{Uuid}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries working with a product for a not allowed Brand or language.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Have not this product_id {{product_id}}”}	Given product is not present in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “This MMO object already present: uuid: {{uuid}}”}	MMO already exists for given language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “URL cant be downloaded”}	User sets incorrect URL or content is not available
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Content type ‘image/jpeg’ is not allowed for type leaflet”}	User sets incorrect {{ContentType}} for given MMO type.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “string”, “Errors”: [ { “ErrorType”: “string”, “FieldPath”: “/Type”, “Parameters”: [ { “name”: “string”, “value”: “string” } ], “Message”: “string” } ]}	Some parameters are not valid or were not provided. See returned message for details.

9.3. Update multimedia objects (MMO)

Request:

URL:	https://bo.icecat.biz/restful/v3/multimedia/{{ProductId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{  “Uuid”: {{Uuid}},  “LangId”: {{lang_id}},  “ShortDescr”: {{ShortDescr}},  “IsPrivate”: true | false,  “Visible”: true | false,  “Link”: {{Link}},  “KeepAsUrl”: true | false,  “Type”: {{Type}},  “ExpiryDate”: “{{YYYY-MM-DD}}“, “EnergyLabellingLink”: “{{EnergyLabellingLink}}”, “IsNewEnergyLabelling”: true | false, “ImagesBatch”: [    {      “Link”: {{Link}},      “Order”: {{Order}}    }  ]}
Comment:	“Uuid”: {{Uuid}} – unique MMO identifier. See 9.1 “Visible” : true parameter will deactivate MMO.

Success response:

Status:	200
Body:	{ “Code”: 200, “Message”: “Updated”, “Uuid”: {{Uuid}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries to work with a product for a not allowed Brand or language.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Have not this product_id {{product_id}}”}	The given product is not present in the Icecat database
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “MMO object is not present in DB”}	MMO is not present in the Icecat database
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “URL can’t be downloaded”}	User sets incorrect URL or content is not available
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Content type ‘image/jpeg’ is not allowed for type leaflet”}	User sets incorrect {{ContentType}} for current MMO type
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “string”, “Errors”: [ { “ErrorType”: “string”, “FieldPath”: “/Type”, “Parameters”: [ { “name”: “string”, “value”: “string” } ], “Message”: “string” } ]}	Some parameters are not valid or are not given. See returned message for details.

10. Product description block – view, create, update or delete

You can add a description to a product or get information about which descriptions we have. The description block contains: marketing text, the official url of the brand, disclaimers, warranty info, full product name, short marketing text, SEO title, SEO description, and SEO keywords. This content is language dependent and per language, we can have only one description block.

Swagger schema – https://api.icecat.biz (ProductDescriptions)

The accounts with user role “brand” can interact only with descriptions in allowed languages. For getting allowed languages see 3.2.1. 

{{Disclaimer}} is mandatory if product has property {{isDangerous}}: true. See p.2.2.

{{Disclaimer}} property can’t contains such values as: CE-certification, CE certification, certification CE, certification-CE, CE-gepruft,  gepruft CE.

Note. “Bullet points” is a part of product description block. However, it has its own rest. See p.11.

10.1. View product description block

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductDescriptions?ProductId={{ProductId}}&AccessKey={{SessionId}}
Method:	GET

Success response:

Status:	200
Body:	{ “Data”: { “Descriptions”: [ { “ProductDescriptionId”: {{ProductDescriptionId}}, “LanguageId”: {{lang_id}}, “ShortDescription”: {{ShortDescription}}, “LongDescription”: {{LongDescription}}, “OfficialUrl”: {{OfficialUrl}}, “WarrantyInfo”: {{WarrantyInfo}}, “SeoTitle”: {{SeoTitle}}, “SeoDescription”: {{SeoDescription}}, “SeoKeywords”: {{SeoKeywords}}, “Disclaimer”: {{Disclaimer}}, “MiddleDescription”: {{ MiddleDescription}} } … ] }}
Comment:	Note. Only descriptions for allowed languages will be shown. Otherwise response will be empty. For getting allowed languages see p.3.2.1.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Requested product does not exist.”}	Given product is not present in the Icecat database.

10.2. Create product description block

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductDescriptions?AccessKey={{SessionId}}
Method:	POST
Body:	{ “ProductId”: {{ProductId}}, “LanguageId”: {{lang_id}}, “ShortDescription”: {{ShortDescription}}, “LongDescription”: {{LongDescription}}, “OfficialUrl”: {{OfficialUrl}}, “WarrantyInfo”: {{WarrantyInfo}}, “SeoTitle”: {{SeoTitle}}, “SeoDescription”: {{SeoDescription}}, “SeoKeywords”: {{SeoKeywords}}, “Disclaimer”: {{Disclaimer}}, “MiddleDescription”: {{ MiddleDescription}} }
Comment:	{{Disclaimer}} is mandatory if product has property {{isDangerous}}: true. See p.2.2.

Success response:

Status:	201
Body:	{ “Data”: { “ProductId”: {{ProductId}}, “ProductDescriptionId”: {{ProductDescriptionId}}, “LanguageId”: {{lang_id}}, “ShortDescription”: {{ShortDescription}}, “LongDescription”: {{LongDescription}}, “OfficialUrl”: {{OfficialUrl}}, “WarrantyInfo”: {{WarrantyInfo}}, “SeoTitle”: {{SeoTitle}}, “SeoDescription”: {{SeoDescription}}, “SeoKeywords”: {{SeoKeywords}}, “Disclaimer”: {{Disclaimer}}, “MiddleDescription”: {{ MiddleDescription}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Requested product does not exist.”}	Given product is not in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is incorrect for you.”}	User sets a not allowed language.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product description already exists.”}	Product description already exists for such language.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Unusable phrase found in ‘Disclaimer’ (like ‘CE-certification’).”}	{{Disclaimer}} property contains values such as CE-certification, CE certification, certification CE, certification-CE, CE-gepruft,  gepruft CE.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Field `Disclaimer` must be filled for a dangerous product.”}	Product has property {{IsDangerous}}: true and user sets an empty value for {{Disclaimer}}

10.3. Update product description block

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductDescriptions/{{ProductDescriptionId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{ “LanguageId”: {{lang_id}}, “ShortDescription”: {{ShortDescription}}, “LongDescription”: {{LongDescription}}, “OfficialUrl”: {{OfficialUrl}}, “WarrantyInfo”: {{WarrantyInfo}}, “SeoTitle”: {{SeoTitle}}, “SeoDescription”: {{SeoDescription}}, “SeoKeywords”: {{SeoKeywords}}, “Disclaimer”: {{Disclaimer}}, “MiddleDescription”: {{ MiddleDescription}} }
Comment:	{{ProductDescriptionId}} – unique identifier. Look at the response p.11.1{{Disclaimer}} is mandatory if product has property {{isDangerous}}: true. See p.2.2.

Success response:

Status:	200
Body:	{ “Data”: { “ProductId”: {{ProductId}}, “ProductDescriptionId”: {{ProductDescriptionId}}, “LanguageId”: {{lang_id}}, “ShortDescription”: {{ShortDescription}}, “LongDescription”: {{LongDescription}}, “OfficialUrl”: {{OfficialUrl}}, “WarrantyInfo”: {{WarrantyInfo}}, “SeoTitle”: {{SeoTitle}}, “SeoDescription”: {{SeoDescription}}, “SeoKeywords”: {{SeoKeywords}}, “Disclaimer”: {{Disclaimer}}, “MiddleDescription”: {{ MiddleDescription}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Requested product does not exist.”}	Given product is not in the Icecat database
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Language ID is incorrect for you.”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product description already exists.”}	Product description already exists for such language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Unusable phrase found in ‘Disclaimer’ (like ‘CE-certification’).”}	{{Disclaimer}} property contains values such as CE-certification, CE certification, certification CE, certification-CE, CE-gepruft,  gepruft CE.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Field `Disclaimer` must be filled for a dangerous product.”}	Product has property {{IsDangerous}}: true and user set empty value for {{Disclaimer}}

10.4. Delete product description

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductDescriptions/{{ProductDescriptionId}}?AccessKey={{SessionId}}
Method:	DELETE
Body:	–
Comment:	{{ProductDescriptionId}} – unique identifier. See 10.1

Success response:

Status:	200
Body:	{ “Data”: []}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries working with a product for a not allowed Brand or language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Product description does not exist.”}	User sets incorrect {{ProductDescriptionId}} or it does not exist

11. Bullet points – view, create, update and delete

We have a separate API for bullet points in the description block. It is language dependent contend as any description mentioned before.

Swagger schema – https://api.icecat.biz (Bullet Points)

11.1. View bullet points

Request:

URL:	https://bo.icecat.biz/restful/v3/BulletPoints?ProductId={{ProductId}}&LanguageId={{lang_id}}&AccessKey={{SessionId}}
Method:	GET

Success response:

Status:	200
Body:	{ “Data”: [ { “BulletPointsId”: {{BulletPointsId}}, “ProductId”: {{ProductId}}, “LanguageId”: {{lang_id}}, “Value”: {{value}} } … ]}
Status:	204
Comment:	Note. Only bullet points for allowed languages will be shown. Otherwise response will be empty. For getting allowed languages see 3.2.1. 1. {{lang_id}} – optional parameter used to filter BulletPoints by selected language

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries to work with product for not allowed Brand or language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “ProductId is unknown”}	Given product is not in the Icecat database

11.2. Create bullet points

Request:

URL:	https://bo.icecat.biz/restful/v3/BulletPoints?AccessKey={{SessionId}}
Method:	POST
Body:	{ “ProductId”: {{ProductId}}, “LanguageId”: {{lang_id}}, “Value”: {{value}} }
Comment:	{{value}} – Use “\n” to separate different bullet points. E.g. “test\ntest2”. Identical bullet points will be merged after saving the values list in the database.

Success response:

Status:	201
Body:	{ “Data”: [ { “BulletPointsId”: {{BulletPointsId}}, “ProductId”: {{ProductId}}, “LanguageId”: {{lang_id}}, “Value”: {{value}} } … ]}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Requested product does not exist.”}	Given product is not in the Icecat database.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “You are not allowed to use passed LanguageId”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Bullet points already exists.”}	Bullet points already exist for such language

11.3. Update bullet points

Request:

URL:	https://bo.icecat.biz/restful/v3/BulletPoints/{{BulletPointsId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{ “LanguageId”: {{lang_id}}, “Value”: {{value}} }
Comment:	{{BulletPointsId}} –  unique identifier. See 11.1.

Success response:

Status:	200
Body:	{ “Data”: [ { “BulletPointsId”: {{BulletPointsId}}, “ProductId”: {{ProductId}}, “LanguageId”: {{lang_id}}, “Value”: {{value}} } … ]}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “You are not allowed to use passed LanguageId”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Nothing to update”}	User sets incorrect bullet point or it does not exist

11.4. Delete bullet point

Request:

URL:	https://bo.icecat.biz/restful/v3/BulletPoints/{{BulletPointsId}}?AccessKey={{SessionId}}
Method:	DELETE
Body:	–
Comment:	{{BulletPointsId}} –  unique identifier. See 11.1.

Success response:

Status:	200
Body:	{ “Data”: [ { “BulletPointsId”: {{BulletPointsId}}, “ProductId”: {{ProductId}}, “LanguageId”: {{lang_id}}, “Value”: {{value}} } … ]}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied.”}	User tries to delete bullet points for a not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Nothing to delete”}	User sets incorrect bullet point or it does not exist.

12. “Reasons to buy” (Product bullets) – view, create, update and delete

In the product, you can add more information about why a client should buy this product. The asset “Reasons to buy”  is language dependent content, and can contain multiple “Reasons to buy” per language. In this asset, you need to add images, descriptions and titles.

Swagger schema – https://api.icecat.biz (Product Bullet)

12.1. View “Reasons to buy” (Product bullets)

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductBullet/{{ProductId}}?AccessKey={{SessionId}}
Method:	GET

Success response:

Status:	200
Body:	{ “Data”: [ { “BulletId”: {{BulletId}}, “ProductId”: {{ProductId}}, “Code”: {{Code}}, “LanguageId”: {{lang_id}}, “Value”: {{Value}}, “Title”: {{Title}}, “IconUrl”: {{IconUrl}}, “IconSize”: 0, “No”: {integer}, “Updated”: {{YYYY-MM-DD HH-MM-SS}}, “IsPrivate”: true | false, “DataSourceId”: {integer} }, …}
Status:	200
	{ “Data”: []}
Comment:	Note. Only product bullets for allowed languages will be shown. Otherwise response will be empty. For getting allowed languages use p.3.2.1.

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied. You don’t have permission”}	User tries working with a product for a not allowed Brand or language
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied.”}	Given product is not in the Icecat database

12.2. Create “Reasons to buy” (Product bullets)

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductBullet/{{ProductId}}?AccessKey={{SessionId}}
Method:	POST
Body:	{ “LanguageId”: {{lang_id}}, “Value”: {{Value}}, “Title”: {{Title}}, “IconUrl”: {{IconUrl}}, “IconSize”: 0, “No”: {integer}, “IsPrivate”: true | false }
Comment:	{{LanguageId}}, {{Value}} and {{Title}} are mandatory and can not be empty

Success response:

Status:	201
Body:	{ “Data”: { “Message”: “Created”, “BulletId”: {{BulletId}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied.”}	Given product is not in the Icecat database
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “You are not allowed to use LanguageId with value {{lang_id}}”}	User sets a not allowed language
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Title can not be empty”}	User gives an empty Title

12.3. Update “Reasons to buy” (Product bullets)

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductBullet/{{BulletId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{ “LanguageId”: {{lang_id}}, “Value”: {{Value}}, “Title”: {{Title}}, “IconUrl”: {{IconUrl}}, “IconSize”: 0, “No”: {integer}, “IsPrivate”: true | false }
Comment:	Allowed to send one or more properties from above{{BulletId}} –  unique identifier. See 12.1.

Success response:

Status:	200
Body:	{ “Data”: { “Message”: “Updated”, “BulletId”: {{BulletId}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “You are not allowed to access this content”}	User sets not allowed language
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied”}	User sets incorrect {{BulletId}} or it does not exist

12.4.  Delete “Reasons to buy” (Product bullets)

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductBullet/{{ProductId}}?AccessKey={{SessionId}}
Method:	DELETE
Body:	[ {{BulletId}}]
Comment:	Allowed to send only one {{BulletId}} per time {{BulletId}} –  unique identifier. See 12.1.

Success response:

Status:	200
Body:	{ “Data”: { “Message”: “Deleted”, “BulletId”: {{BulletId}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “You are not allowed to access this content”}	User tries to delete a product’s bullets for a not allowed language
404	{ “Code”: 404, “Error”: “Not Found”, “Message”: “BulletId is not found”}	User sets incorrect {{BulletId}} or it does not exist
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied”}	User sets incorrect {{ProductId}} or it does not exist

13. View, create and update product images (Gallery)

You can add images to the product. This asset can be language dependent or you can choose International if this image will be for all languages. We have several special parameters in the image like: 
– is private: it means that this image will be seen only by authorized shops (resellers)

– expiration date: this image will stop to be seen per this date 

Swagger schema – https://api.icecat.biz (Gallery)

The accounts with user role “brand” can not delete product images. Use the {{Visible}}: false parameter to deactivate it instead. See 13.3.

Note. The accounts with user role “brand” can view or interact only with international images and images for allowed languages. For getting allowed languages see p.3.2.1.

The same image can have multiples entries in the {{Locales}} section with different {{GalleryId}} and {{lang_id}}.

13.1. View product images

Request:

URL:	https://bo.icecat.biz/restful/v3/Gallery/{{ProductId}}?AccessKey={{SessionId}}
Method:	GET

Success response:

Status:	200
Body:	{  “Data”: [    {      “OrderNumber”: 0,      “Md5”: “string”,      “ImageFingerprint”: “string”,      “Origin”: {        “Link”: “string”,        “Size”: 0      },      “High”: {        “Link”: “string”,        “Height”: 0,        “Width”: 0,        “Size”: 0      },      “Medium”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Low”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Thumb”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Locales”: [        {          “GalleryId”: {{GalleryId}},          “LanguageId”: {{lang_id}},          “IsPrivate”: true | false,          “ExpiryDate”: “string”,          “Visible”: true | false,          “Type”: “ProductImage”,          “EditorUserId”: 0,          “DataSourceId”: 0,          “Updated”: {{YYYY-MM-DD HH:MM:SS}},          “SourceLink”: “string”,          “Expired”: true | false,          “CanActivate”: true | false,          “FileName”: “string”        }       …      ]    }   …  ],  “CanDelete”: false,  “AllowedLanguages”: [    {{lang_id}}  ],  “CurrentDate”: {{YYYY-MM-DD}}}
Status:	200
	{    “Data”: [],    “CanDelete”: false,    “AllowedLanguages”: [        {{lang_id}}    ],    “CurrentDate”: {{YYYY-MM-DD}}}
Comment:	Only images for international and allowed languages will be shown. Otherwise the response will be empty.

Error responses:

Status	Body	Comment
401	{  “Code”: 401,  “Error”: “Unauthorized”,  “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{  “Code”: 403,  “Error”: “Forbidden”,  “Message”: “Access denied. You don’t have permission”}	User tries working with a product for a not allowed Brand or language
404	{    “Code”: 404,    “Error”: “Not Found”,    “Message”: “Requested product is not present in Icecat database.”}	Given product is not in the Icecat database

13.2. Add images to the product gallery

A user can add new images to the product gallery or copy existing images to another locale. See below. The width and height of an image must be not less than 200 px.

Allowed image formats are: image/jpeg, image/png, image/tiff, image/bmp, image/x-windows-bmp, image/x-ms-bmp, image/webp.

{{OrderNumber}} is an optional parameter and has the following behavior:

– User sends {{OrderNumber}} that already exists then the {{OrderNumber}} is set, and all other subsequent numbers will be moved +1.

– User sends an image that already exists for another locale then both images will get a new {{OrderNumber}}.

– User does not send {{OrderNumber}}: then it will be appended to the end of the gallery list.

13.2.1. Add new image to product gallery

Note. The user must send {{Metadata}} in JSON format as form-data. 
Request:

URL:	https://bo.icecat.biz/restful/v3/Gallery/{{ProductId}}?AccessKey={{SessionId}}
Method:	POST
Metadata:	{ “Link”: “String – valid URI of an image. Mandatory”,”LanguageId”: {{lang_id}}, – Mandatory”OrderNumber”: {{OrderNumber}},”IsPrivate”: true | false,”ExpiryDate”: {{YYYY-MM-DD}}, Expiry date must be greater than the current date.”FileName”: “String. Optional property.”,”Type”: “String. Optional property. By default – ProductImage. Must contain one of these constants: ProductImage, ProductAward, LifestyleImage, ProductPackagingImage, ProductImageAnnotated, ProductDetailImage, Screenshot, PackageContents, Schema/Chart, Other, ProductImageFront-Center, ProductImageLeft, ProductImageRight, ProductImageTop, ProductImageBottom, ProductImageRear, ProductImageFront-Left, ProductImageFront-Right, PackshotFront-Center, PackshotBottom, PackshotRear, PackshotFront-Left, PackshotFront-Right, ProductImagePEGI, ProductImageUSK, ProductImageESRB” }
Comment:

Success response:

Status:	201
Body:	{  “Data”: [    {      “OrderNumber”: 0,      “Md5”: “string”,      “ImageFingerprint”: “string”,      “Origin”: {        “Link”: “string”,        “Size”: 0      },      “High”: {        “Link”: “string”,        “Height”: 0,        “Width”: 0,        “Size”: 0      },      “Medium”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Low”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Thumb”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Locales”: [        {          “GalleryId”: {{GalleryId}},          “LanguageId”: {{lang_id}},          “IsPrivate”: true | false,          “ExpiryDate”: “string”,          “Visible”: true | false,          “Type”: “ProductImage”,          “EditorUserId”: 0,          “DataSourceId”: 0,          “Updated”: {{YYYY-MM-DD HH:MM:SS}},          “SourceLink”: “string”,          “Expired”: true | false,          “CanActivate”: true | false,          “FileName”: “string”        }       …      ]    }   …  ],  “CanDelete”: true | false,  “AllowedLanguages”: [    {{lang_id}}  ],  “CurrentDate”: {{YYYY-MM-DD}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{  “Code”: 401,  “Error”: “Unauthorized”,  “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
404	{    “Code”: 404,    “Error”: “Not Found”,    “Message”: “Requested product is not present in Icecat database.”}	Given product is not in the Icecat database.
403	{    “Code”: 403,    “Error”: “Forbidden”,    “Message”: “You are not allowed to modify requested content.”}	User sets not allowed language
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Failed to download image.”}	URI of an image is incorrect or image is not available
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Image already exists.”}	Such image already exists for such language
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “The image is too small. The width cannot be smaller than 200 pixels.”}	Image resolution is too small
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Only files with these MIME types are allowed: image/jpeg, image/png, image/tiff, image/bmp, image/x-windows-bmp, image/x-ms-bmp.”}	Image link contains incorrect file format extension
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: {{Message}},    “Errors”: [        {            “ErrorType”: “”,            “FieldPath”: “”,            “Parameters”: [],            “Message”: {{Message}}        }    ]}	Some of the parameters are not valid or are not provided. See returned message for details

13.2.2. Copy existing image to another locale in product gallery

Request:

URL:	https://bo.icecat.biz/restful/v3/Gallery/{{ProductId}}/Locale?AccessKey={{SessionId}}
Method:	POST
Body:	{  “GalleryId”: {{GalleryId}},  “LanguageId”: [    {{lang_id}}  ]}
Comment:	{{GalleryId}} look at the p.13.1.

Success response:

Status:	201
Body:	{  “Data”: [    {      “OrderNumber”: 0,      “Md5”: “string”,      “ImageFingerprint”: “string”,      “Origin”: {        “Link”: “string”,        “Size”: 0      },      “High”: {        “Link”: “string”,        “Height”: 0,        “Width”: 0,        “Size”: 0      },      “Medium”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Low”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Thumb”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Locales”: [        {          “GalleryId”: {{GalleryId}},          “LanguageId”: {{lang_id}},          “IsPrivate”: true | false,          “ExpiryDate”: “string”,          “Visible”: true | false,          “Type”: “ProductImage”,          “EditorUserId”: 0,          “DataSourceId”: 0,          “Updated”: {{YYYY-MM-DD HH:MM:SS}},          “SourceLink”: “string”,          “Expired”: true | false,          “CanActivate”: true | false,          “FileName”: “string”        }       …      ]    }   …  ],  “CanDelete”: true | false,  “AllowedLanguages”: [    {{lang_id}}  ],  “CurrentDate”: {{YYYY-MM-DD}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{  “Code”: 401,  “Error”: “Unauthorized”,  “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
404	{    “Code”: 404,    “Error”: “Not Found”,    “Message”: “Requested product is not present in Icecat database.”}	Given product is not in the Icecat database
403	{    “Code”: 403,    “Error”: “Forbidden”,    “Message”: “You are not allowed to modify requested content.”}	User sets not allowed language
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Gallery ID is unknown.”}	User set incorrect {{GallerId}} or it does not exist
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Unable to copy image. Some image(s) already exists. Gallery IDs: {{GalleryId}}”}	Such image already exists for such language
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: {{Message}},    “Errors”: [        {            “ErrorType”: “”,            “FieldPath”: “”,            “Parameters”: [],            “Message”: {{Message}}        }    ]}	Some of the parameters are not valid or are not provided. See returned message for details.

13.3. Update image in product gallery

Request:

URL:	https://bo.icecat.biz/restful/v3/Gallery/{{ProductId}}/{{GalleryId}}?AccessKey={{SessionId}}
Method:	PATCH
Body:	{“OrderNumber”: {{OrderNumber}},“IsPrivate”: true | false,“ExpiryDate”: {{YYYY-MM-DD}}, Expiry date must be greater than the current date.“FileName”: “String. Optional property.”,“Type”: “String. Optional property. By default – ProductImage. Must contain one of these constants: ProductImage, ProductAward, LifestyleImage, ProductPackagingImage, ProductImageAnnotated, ProductDetailImage, Screenshot, PackageContents, Schema/Chart, Other, ProductImageFront-Center, ProductImageLeft, ProductImageRight, ProductImageTop, ProductImageBottom, ProductImageRear, ProductImageFront-Left, ProductImageFront-Right, PackshotFront-Center, PackshotBottom, PackshotRear, PackshotFront-Left, PackshotFront-Right, ProductImagePEGI, ProductImageUSK, ProductImageESRB”}
Comment:	{{GalleryId}} see 13.1.

Success response:

Status:	201
Body:	{  “Data”: [    {      “OrderNumber”: 0,      “Md5”: “string”,      “ImageFingerprint”: “string”,      “Origin”: {        “Link”: “string”,        “Size”: 0      },      “High”: {        “Link”: “string”,        “Height”: 0,        “Width”: 0,        “Size”: 0      },      “Medium”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Low”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Thumb”: {        “Link”: “string”,        “Size”: 0,        “Height”: 0,        “Width”: 0      },      “Locales”: [        {          “GalleryId”: {{GalleryId}},          “LanguageId”: {{lang_id}},          “IsPrivate”: true | false,          “ExpiryDate”: “string”,          “Visible”: true | false,          “Type”: “ProductImage”,          “EditorUserId”: 0,          “DataSourceId”: 0,          “Updated”: {{YYYY-MM-DD HH:MM:SS}},          “SourceLink”: “string”,          “Expired”: true | false,          “CanActivate”: true | false,          “FileName”: “string”        }       …      ]    }   …  ],  “CanDelete”: true | false,  “AllowedLanguages”: [    {{lang_id}}  ],  “CurrentDate”: {{YYYY-MM-DD}}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “Access denied.”}	Given product is not the in Icecat data base
400	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “You are not allowed to modify requested content.”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Gallery ID is unknown.”}	User sets incorrect {{GallerId}} or it does not exist
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: {{Message}}, “Errors”: [ { “ErrorType”: “”, “FieldPath”: “”, “Parameters”: [], “Message”: {{Message}} } ]}	Some of the parameters are not valid or are not provided. See returned message for details

14. Product static relations – view, create, update and delete

You can add a relation between your product and another. This relation is language dependent. You can add a date when this relation starts and finishes.

Swagger schema – https://api.icecat.biz (ProductStaticRelations)

Static relations – these are product to product relations. All static relations are bidirectional. 

Some relations have a preferred status – it means that these relations are “recommended” by the respective brand.

A product can’t be related to itself.

To add new language to existing relation see 14.3.

To modify parameters for an existing language in an existing relation see 14.4.

Users with role “brand” can delete the whole relation only if the relation includes only locales for which the brand user is authorized – see 14.5. (Note. A brand user that has set “International” as its language has access to all locales. In all other cases, a user can delete only the allowed locale from a product relation. See 14.6.)

14.1. View static product relations

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductStaticRelations?{{ProductId}}&AccessKey={{SessionId}}
Method:	GET

Success response:

Status:	200
Body:	{  “Data”: [  {  “RelationId”: {{RelationId}},  “FirstProductId”: {{FirstProductId}},  “SecondProductId”: {{SecondProductId}},  “Locales”: [   {  “LanguageId”: {{lang_id}},  “RecomendedByBrand”: true | false,  “RecomendedByBrandFrom”: {{YYYY-MM-DD}},  “RecomendedByBrandTill”: {{YYYY-MM-DD}}   },   …  ]  },  … ]}
Status:	200
	{    “Data”: []}
Comment:	Note. If a product has static relations for not allowed languages then no such relations will be shown. The {{Locales}} section will be empty or only allowed locales will be shown.

Error responses:

Status	Body	Comment
401	{  “Code”: 401,  “Error”: “Unauthorized”,  “Message”: “Unauthorized”}	User input incorrect {{SessionId}}
403	{    “Code”: 403,    “Error”: “Forbidden”,    “Message”: “You do not have an access to first product.”}	User tries working with a product for a not allowed Brand or language
400	{  “Code”: 400,  “Error”: “Bad request”,  “Message”: “Invalid product id.”}	Given product already is not in the Icecat database.

14.2. Create product static relations

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductStaticRelations?AccessKey={{SessionId}}
Method:	POST
Body:	{  “FirstProductId”: {{FirstProductId}},  “SecondProductId”: {{SecondProductId}},  “Locales”: [    {      “LanguageId”: {{lang_id}},      “RecommendedByBrand”: true | false,      “RecommendedByBrandFrom”: {{YYYY-MM-DD}},      “RecommendedByBrandTill”: {{YYYY-MM-DD}}    },    …  ]}
Comment:	{{Locales}}.{{LanguageId}} is mandatory and can not be empty. A user can add more than one Locale at the same time.

Success response:

Status:	201
Body:	{  “Data”: [  {  “RelationId”: {{RelationId}},  “FirstProductId”: {{FirstProductId}},  “SecondProductId”: {{SecondProductId}},  “Locales”: [   {  “LanguageId”: {{lang_id}},  “RecomendedByBrand”: true | false,  “RecomendedByBrandFrom”: {{YYYY-MM-DD}},  “RecomendedByBrandTill”: {{YYYY-MM-DD}}   },   …  ]  },  … ]}
Comment:	–

Error responses:

Status	Body	Comment
401	{  “Code”: 401,  “Error”: “Unauthorized”,  “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Invalid product id {{ProductId}}.”}	User sets incorrect or absent {{ProductId}} for first or second product.
403	{    “Code”: 403,    “Error”: “Forbidden”,    “Message”: “You do not have an access to one of the locales.”}	User sets not allowed language
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “Relation between given products already exists.”}	Relation between given products already exists. Note: to add a new locale to an existing relation see 15.3.
400	{    “Code”: 400,    “Error”: “Bad Request”,    “Message”: “/Locales/0/LanguageId is required”,    “Errors”: [        {            “ErrorType”: “required”,            “FieldPath”: “/Locales/0/LanguageId”,            “Parameters”: [],            “Message”: “/Locales/0/LanguageId is required”        }    ]}	User sets empty {{Locales}}

14.3. Add new language to existing product static relations

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductStaticRelations/{{RelationId}}/Locales?AccessKey={{SessionId}}
Method:	POST
Body:	{ “LanguageId”: {{lang_id}}, “RecomendedByBrand”: true | false, “RecomendedByBrandFrom”: {{YYYY-MM-DD}}, “RecomendedByBrandTill”: {{YYYY-MM-DD}} }
Comment:	{{RelationId}} – see 14.1.

Success response:

Status:	201
Body:	{ “Data”: { “LanguageId”: {{lang_id}}, “RecommendedByBrand”: true | false, “RecommendedByBrandFrom”: {{YYYY-MM-DD}}, “RecommendedByBrandTill”: {{YYYY-MM-DD}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “You do not have an access to one of the locales.”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid relation id.”}	User sets incorrect {{RelationId}} or it does not exist.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Locale already exists.”}	Such locale already exists for this relation.

14.4. Modify existing locale in product static relations

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductBullet/{{ProductId}}?}/Locales/{{lang_id}}AccessKey={{SessionId}}
Method:	PATCH
Body:	{ “RecommendedByBrand”: true | false, “RecommendedByBrandFrom”: {{YYYY-MM-DD}}, “RecommendedByBrandTill”: {{YYYY-MM-DD}}}
Comment:	{{RelationId}} – use p.14.1.

Success response:

Status:	200
Body:	{ “Data”: { “LanguageId”: {{lang_id}}, “RecommendedByBrand”: true | false, “RecommendedByBrandFrom”: {{YYYY-MM-DD}}, “RecommendedByBrandTill”: {{YYYY-MM-DD}} }}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “You do not have an access to one of the locales.”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid relation id.”}	User set incorrect {{RelationId}} or it does not exist
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid language id.”}	User sets incorrect {{lang_id}} or such locale does not exist in the given product relation.

14.5. Delete static product relations

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductStaticRelations/{{RelationId}}?AccessKey={{SessionId}}
Method:	DELETE
Body:
Comment:	If the relation includes only locales, to which the brand user is assigned.

Success response:

Status:	200
Body:	{ “Data”: {}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “You do not have an access to one of the locales.”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid relation id.”}	User sets incorrect {{RelationId}} or it does not exist

14.6 Delete locale from product static relations

Request:

URL:	https://bo.icecat.biz/restful/v3/ProductStaticRelations/{{RelationId}}/Locales/{{lang_id}}?AccessKey={{SessionId}}
Method:	DELETE
Body:
Comment:

Success response:

Status:	200
Body:	{ “Data”: {}}
Comment:	–

Error responses:

Status	Body	Comment
401	{ “Code”: 401, “Error”: “Unauthorized”, “Message”: “Unauthorized”}	User input: incorrect {{SessionId}}
403	{ “Code”: 403, “Error”: “Forbidden”, “Message”: “You do not have an access to one of the locales.”}	User sets not allowed language
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid relation id.”}	User sets incorrect {{RelationId}} or it does not exist.
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Invalid language id.”}	User sets incorrect {{lang_id}} or such locale does not exist in product relation
400	{ “Code”: 400, “Error”: “Bad Request”, “Message”: “Can’t delete the last locale of the relation.”}	User can not delete the last locale of the relation with this method. To delete the whole product relation see 14.5.