Marketplaces / B&Q / B&Q - Product & Offer management / B&Q - Create Product

B&Q - Create Product

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Date	Version	Name	Applied changes
19/10/2022	1.0		Initial Version

The purpose of this document is to detailed describe the flow of creating product.

In order to create a product we will need to make couple of API Calls, which are POST P41 ( Import products to the operator information system), GET P42 (Get the import status for a product import) , GET P44 (Get the error report file for a product import), GET P47 (Get the transformation error report file for a product import)

How to handle variations in MIRAKL

The way we treat a product as a Variation is when we have Product Account > Variation Group populated. Each Product Account in Hemi can have Item Specifics and Variation Specifics which we validate the same way against the MIRAKL taxonomy but we use them only in certain cases.

If we DO NOT HAVE Product Account > Variation Group:

We use only the Item Specifics from the product if any Variation Specifics are also populated we ignore them

If we HAVE Product Account > Variation Group:

We use all of the Variation Specifics and all of the Item Specifics. If there are no Variation Specifics we should return an error. If we have the same attribute added as a Variation Specific and as a Item Specific we pick it only from the Variation Specifics.

Please note we do not need to select all variants if only one them is set for revision or creation because they goes as separate products on MIRAKL and the only thing which associate them is the Mirakl_ProductGroup_ID. So we can add variants to a variation group only by specifying the correct Mirakl_ProductGroup_ID. If we want to remove a product from a variation we need to push the product for update again without the Mirakl_ProductGroup_ID.

POST P41 - Import products to the operator information system

API Call: /api/products/imports

API Docs: https://marketplace.kingfisher.com/help/api-doc/seller/mmp.html#P41

Complete flow:

In order to push products for creation we should have:

Product status = Awaiting Creation ; Listing Status **= Inactive; List/Update the whole item= Pending**

If we successfully pick a product for creation, we will have following statuses:

Product status -Awaiting Creation ; Listing Status - Inactive; List/Update the whole Item = Sent

If the internal product validation is not successful and we receive an error, we will set following statuses and store the relevant error message in Item Account > Update Item Error:

Product status = Awaiting Creation ; Listing Status=Inactive; List/Update the whole item= Error

If we receive success after performing P42 (when we send product to MIRAKL & When both "has_error_report" and "has_transformation_error_report" are equal to “false“ ) we can proceed to following:

Product status -Product Created ; Listing Status - Inactive; List/Update the whole Item = Pending

There will be two cases how to handle channel item ids in MIRAKL depends on the type. The first case is after successful product creation we need to fill the Channel Item ID, which will be the SKU. The second option is to use P31 Get products for a list of product references which will map the SKUs between Hemi and MIRAKL and store the MIRAKL id as Channel Item ID. For B&Q integration we will go for second option.

If we receive an error (any of "has_error_report" and "has_transformation_error_report" are equal to “true“):

Product status -Awaiting Creation ; Listing Status - Inactive; List/Update the whole Item = Error

And we need to store the relevant error message into the Product Account >Update Item Error.

Parameter	Notes	Required
File	Import file (CSV or XML or XLSX) to upload. Use `multipart/form-data` with name `file`	Yes
operator_format	Force the use of the operator product format
No

Note: Every time we send products for creation we have to do internal check if all required attributes are part of the the product as Item Specifics or Variation Specifics according to their taxonomy which we download and store on the instance.

The file which we will import must be an xml file with the following structure:

Example File:

PIM_14538-example.xml

<?xml version="1.0" encoding="UTF8"?>
<import>
<products>
<product>
<attribute>
<code>category</code>
<value>PIM_11123</value>
</attribute>
<attribute>
<code>shop_sku</code>
<value/>
</attribute>
<attribute>
<code>name</code>
<value/>
</attribute>
<attribute>
<code>ean</code>
<value/>
</attribute>
<attribute>
<code>image_main_1</code>
<value/>
</attribute>
<attribute>
<code>Mirakl_ProductGroup_ID</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_1</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_2</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_3</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_4</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_5</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_6</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_7</code>
<value/>
</attribute>
<attribute>
<code>image_secondary_8</code>
<value/>
</attribute>
<attribute>
<code>pdf_product_guide</code>
<value/>
</attribute>
<attribute>
<code>pdf_product_instruction_manual</code>
<value/>
</attribute>
<attribute>
<code>pdf_safety_manual</code>
<value/>
</attribute>
<attribute>
<code>video</code>
<value/>
</attribute>
<attribute>
<code>Unique Selling Point 01</code>
<value>Compact size of only 50cm x 40cm</value>
</attribute>
<attribute>
<code>Unique Selling Point 02</code>
<value>Features soft close mechanism for a seamless close</value>
</attribute>
<attribute>
<code>Unique Selling Point 03</code>
<value>All the materials have been thoroughly tested to ensure a high performance and longevity</value>
</attribute>
<attribute>
<code>Unique Selling Point 04</code>
<value>Simple and modern design</value>
</attribute>
<attribute>
<code>Unique Selling Point 05</code>
<value>The door can be installed to open on the right or left side</value>
</attribute>
<attribute>
<code>Unique Selling Point 06</code>
<value>Includes soft hinges with an easy clip system</value>
</attribute>
<attribute>
<code>Unique Selling Point 07</code>
<value>Made in the UK</value>
</attribute>
<attribute>
<code>Unique Selling Point 08</code>
<value>Features preset hardware and antiderailment wheels</value>
</attribute>
<attribute>
<code>Acquisition brand</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Core_Pack quantity</code>
<value>50</value>
</attribute>
<attribute>
<code>Core_Pack type</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Body Copy</code>
<value>Available in a range of designs and styles, the Atomia collection is a modular storage furniture solution that can fit from floor to ceiling in any space  no matter how awkward.</value>
</attribute>
<attribute>
<code>Selling Copy</code>
<value>The Atomia cabinets are available in White, Oak effect, and Grey Oak effect. These are perfect for creating anything from a wardrobe to a bedside cabinet.</value>
</attribute>
<attribute>
<code>Key_Feature</code>
<value>3.5 Litre Bowl</value>
</attribute>
<attribute>
<code>Guarantee</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>reach_verified</code>
<value/>
</attribute>
<attribute>
<code>contains_wood</code>
<value/>
</attribute>
<attribute>
<code>fsc_pecl_certified</code>
<value/>
</attribute>
<attribute>
<code>Core_Product type</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Bath_panel_type</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Type_Range</code>
<value>Ardesio</value>
</attribute>
<attribute>
<code>Coverage</code>
<value>Please provide numeric values only, m² will be applied automatically as the default Unit of Measure. For example, 10m².</value>
</attribute>
<attribute>
<code>Product_height</code>
<value>Please provide numeric values only, mm will be applied automatically as the default Unit of Measure. For example, 60mm.</value>
</attribute>
<attribute>
<code>Product_thickness</code>
<value>Please provide numeric values only, mm will be applied automatically as the default Unit of Measure. For example, 5mm.</value>
</attribute>
<attribute>
<code>Product_width</code>
<value>Please provide numeric values only, mm will be applied automatically as the default Unit of Measure. For example, 20mm.</value>
</attribute>
<attribute>
<code>Vdesc_Colour</code>
<value>Turquoise</value>
</attribute>
<attribute>
<code>Vdesc_Colour group</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Vdesc_Effect</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Vdesc_Finish</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Tech_Material</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Vdesc_Product shape</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Vdesc_Style</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Tech_Fittings & fixings included</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Tech_Handed</code>
<value>Use dropdown list</value>
</attribute>
<attribute>
<code>Product_weight</code>
<value>Please provide numeric values only, g will be applied automatically as the default Unit of Measure. For example, 500g.</value>
</attribute>
<attribute>
<code>Compatibility</code>
<value>Lightwave L2 link plus.</value>
</attribute>
<attribute>
<code>Instructions_for_fitting</code>
<value>Place the product in the desired position to be secured. With the fixings provided, attach the product to the wall.</value>
</attribute>
</product>
</products>

Mapping: Please note N/A means we exclude it from the payload.

Mirakl Field	Mirakl Notes	Integration Required	Hemi Field
`category`	B&Q PIM category code	REQUIRED	Product Account > Primary Category ID
`shop_sku`	Seller unique product identifier / product code	REQUIRED	Product > SKU
`name`	Product description	REQUIRED	Product Account > Title
`ean`	Unique product barcode	REQUIRED	Product Account > Marketplace EAN

OR Product > EAN | If we do not have EAN filled, we should display an error ( EAN is required and we could not proceed to product creation without EAN) Product Account > Marketplace EAN is with priority | | image_main_1 | Primary product image - see product publishing guide for imagery guidelines | REQUIRED | Product > Main Image OR Product Account B&Q> Main Image | Product Account B&Q is with priority | | Root Attributes Above | | | | | | image_secondary_1 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_2 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_3 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_4 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_5 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_6 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_7 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | image_secondary_8 | Additional product image - see product publishing guide for imagery guidelines | RECOMMENDED | Product > More Picture URL Image OR Product Account B&Q > More Images | B&Q specificsProduct Account B&Q is with priority | | pdf_product_guide | Product guide if available to support customer purchase | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | pdf_product_instruction_manual | Product instruction manual where required | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | pdf_safety_manual | Product safety manual where required | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | video | Product video - see product publishing guide for guidelines | RECOMMENDED | Product > Video URL | B&Q specifics | | Unique Selling Point 01 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 02 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 03 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 04 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 05 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 06 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 07 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Unique Selling Point 08 | A product specific feature or unique selling point. Brief descriptive text, called out via a bullet point. Describe any special features the product has. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Acquisition brand | Defines the customer facing brand name of the product. | REQUIRED | Product Account> Item specifics OR Product > Brand | B&Q specificsProduct Account > Item Specifics is with priority | | Core_Pack quantity | Defines the number of products supplied when purchasing a single stock keeping unit (SKU). | REQUIRED | Product Account> Item specifics | B&Q specifics | | Core_Pack type | Defines how the product is supplied. Each – Single item Pack – More than one identical items sold under one SKU. Set – Multiple different items sold under one SKU. Pair – 2 matching items under one SKU or 1 item that is commonly referred as 2(i.e. door handles, shoes, gloves). | REQUIRED | Product Account> Item specifics | B&Q specifics | | Body Copy | Product information - A paragraph of free text that introduces the product, where it might be used or what it is used for. | REQUIRED | Product Account > Description | B&Q specifics | | Selling Copy | Features & Benefits - A paragraph of free text that sits above the individual feature bullets. Contains range and specific product messaging that positions a product to customers. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Key_Feature | Defines call out feature that comes as part of the product for search purposes, used in Marketplace product title only. | RECOMMENDED | Product Account> Item specifics | B&Q specifics | | Guarantee | States the duration of time the product is covered by a formal assurance (guarantee) that certain conditions will be fulfilled, especially that a product will be repaired or replaced if not of a specified quality. If you provide no additional guarantee above the legal minimum, 'Statutory' must be selected. | REQUIRED | Product Account> Item specifics | B&Q specifics | | reach_verified | Is the product Registration, Evaluation, Authorisation & restriction of Chemicals compliant? | REQUIRED | Product Account> Item specifics | B&Q specifics | | contains_wood | Does product contain wood? (yes/no options) | REQUIRED | Product Account> Item specifics | B&Q specifics | | fsc_pecl_certified | Is the product Forest Stewardship Council or Programme for the Endorsement of Forest Certification certified? | REQUIRED | Product Account> Item specifics | B&Q specifics | | Mirakl_ProductGroup_ID | MultiSKU Product Group ID | RECOMMENDED | Product Account > Variation Group | B&Q specifics | | Core_Product type | Defines the basic identifier of the product, which when used on its own will clearly define the product without any further description. | REQUIRED | Product Account> Item specifics | B&Q specifics |

Example Response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<product_import_tracking>
    <import_id>2035</import_id>
</product_import_tracking>

After each successfully send feed for creation we will receive the feed id from the response and need to store it in Marketplace Feeds table.

Mirakl Field	Hemi Field	Comment
import_id	Marketplace Feed > External ID
	Marketplace Feed > Account	For which account is the feed generated.
	Marketplace Feed > Type	Hardcoded as “Listing Create“
	Marketplace Feed > Submitted Date	When the feed is submitted
	Marketplace Feed > Sent Objects Count	How many products we have pushed in the feed

Please note we will also add the feed objects which after processing need to be removed.

GET P42 -Get the import status for a product import

API Call: /api/products/imports/{import}

API Docs: https://marketplace.kingfisher.com/help/api-doc/seller/mmp.html#P42

Example response:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<product_import_tracking>
    <import_id>2005</import_id>
    <date_created>2019-04-05T12:56:21Z</date_created>
    <has_error_report>false</has_error_report>
    <has_new_product_report>false</has_new_product_report>
    <has_transformation_error_report>false</has_transformation_error_report>
    <has_transformed_file>true</has_transformed_file>
    <import_status>SENT</import_status>
    <shop_id>2000</shop_id>
    <transform_lines_in_error>0</transform_lines_in_error>
    <transform_lines_in_success>1</transform_lines_in_success>
    <transform_lines_read>1</transform_lines_read>
    <transform_lines_with_warning>0</transform_lines_with_warning>
</product_import_tracking>

Depends on the response of: "has_error_report" and "has_transformation_error_report" we will need to call each of the error reports if we receive "true". Also if we already have the item pushed into another feed from the same type we remove it from the objects (table 2511) and need to add it in the latest sent feed. Via this way we wont read any old or previous responses for the particular SKU.

When both "has_error_report" and "has_transformation_error_report" are equal to “false“ is the success case (Import status = Completed) and we could proceed to creating and offer to this product.

If we receive success (When both "has_error_report" and "has_transformation_error_report" are equal to “false“ ) we can proceed to following:

Product status -Product Created ; Listing Status - Inactive; List/Update the whole Item = Pending

If we receive an error (any of "has_error_report" and "has_transformation_error_report" are equal to “true“):

Product status -Awaiting Creation ; Listing Status - Inactive; List/Update the whole Item = Error

And we need to store the relevant error message into the Product Account >Update Item Error.

GET P44 - Get the error report file for a product import

We need to perform this call if we receive has_error_report = true, into the response from P42;

API Call: API Call: /api/products/imports/{import}/error_report

API Docs: https://marketplace.kingfisher.com/help/api-doc/seller/mmp.html#P44

Basically, we read the report and we extract the SKU column. After that we compare the Errors columns and we need to store them.

Also, the record for the SKUs that have matched need to be removed from Marketplace Feed Object table.

We will consider Warning=Success in the B&Q integration (it is kind of standard on every MIRAKL) (To be checked and confirmed for the B&Q)

Sample file

product-import-errors-file-20220929110013 (1).csv

GET P47 - Get the transformation error report file for a product import

This call returns if the import is successful and how may warnings and errors we have in the file. We need to call this if we receive has_transformation_error_report = true

API Call: /api/products/imports/{import}/transformation_error_report

API Docs: https://marketplace.kingfisher.com/help/api-doc/seller/mmp.html#P47

Sample file - To be added

GET P31 - Get products for a list of product references API Call: /api/productsAPI Docs: https://marketplace.kingfisher.com/help/api-doc/seller/mmp.html#P31 Sample Request: API call: GET https://marketplace.kingfisher.com/api/products?product_references=EAN|1234567890123 We will be using the EAN in order to obtain the product Ids. Please note we can specify many product_references in single request like: https://marketplace.kingfisher.com/api/products?product_references=EAN|1234567890123,EAN|123456789012,EAN|1234567890123,EAN|1234567895123 etc. Samples Response:
```
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<body>
    <total_count>1</total_count>
    <products>
        <product>
            <category_code>5110114</category_code>
            <category_label>Coffee Machines</category_label>
            <product_id>9312432012041</product_id>
            <product_id_type>EAN</product_id_type>
            <product_sku>MKP100000000037254</product_sku>
            <product_title>Breville Cafe Roma Stainless Espresso/Cappuccino Machine-ESP8C</product_title>
        </product>
    </products>
</body>
```
From the response we get the product_id and store it as Product Account > Channel Item ID.

Additional Information:

For this integration we will need to make sure the protect flags are working as expected:

Protect Quantity (Stop all quantity updates) - Applicable for already created offers. If the offer is not created this flag is ignored. If Protect Quantity = Yes and Update Quantity = Pending - We skip the product If Protect Quantity = Yes and Update Price= Pending - We pick the product only for price update and do NOT include the quantity in the payload If Protect Quantity = Yes and List/Update the Whole Item = Pending - We pick the product for full update but do NOT include the quantity in the payload

Protect Price (Stop all price updates) -Applicable for already created offers. If the offer is not created this flag is ignored. If Protect Price = Yes and Update Quantity = Pending -We pick the product only for stock update and do NOT include the prices in the payload If Protect Price = Yes and Update Price= Pending - We skip the product If Protect Price = Yes and List/Update the Whole Item = Pending - We pick the product for full update but do NOT include the prices in the payload

Protect the whole item - (Stop all product updates apart from Quantity) -Applicable for already created offers. If the offer is not created this flag is ignored. If Protect the whole item = Yes and Update Quantity = Pending -We send the quantity only If Protect the whole item = Yes and Update Price= Pending - We skip the product If Protect the whole item = Yes and List/Update the Whole Item = Pending - We skip the product

Closed -will stop all the updates to the MPs apart from the end item (send 0 stock update). This flag applies for all products the ones which are created and all new products.

Is this article helpful?

0 0 0