IMPORTANTBefore starting any development activity, make sure to have followed all the steps reported in the Register your Integrator Account guide that you can download from this page.
Introduction
The possibility of creating new listings is a capability that every solution integrated with Amazon should provide to guarantee the best Seller experience.
Developing a high-quality Listings Creation functionality requires knowledge of a number of key aspects, both from the business and the technical side of Amazon.
This guide assumes a basic knowledge of MWS, as well as the main differences between the two file types (Amazon Feeds), used to push data to Amazon systems:
- Flat Files: A tab-delimited text file. One different file per categories and per Marketplace here [PDF]
- XML files: One product feed for all the categories for all the Marketplaces. Five XML feeds (Product,
Inventory, Price, Stock, Relationship) to create a Product here [PDF]
In this document, unless explicitly stated, we refer to XML technology.
In order to develop an effective Listing Creation Capability in your application you should have knowledge of Amazon’s business and technical requirements for listing products. For each of them you should:
- Follow Amazon’s Design & Development Best Practices
- Create a User Experience in your solution which will easily guide Sellers according to your design
This manual will guide you through these concepts.
Validate your XMLs
XMLs must be validated against the XSDs.You should always validate your XMLs against Amazon XSDs before submitting them to Amazon. You can use a public parser (e.g. DOM, SAX) to verify that your XMLs match against the schemas.Keep also in mind that this validation is a necessary but not sufficient condition to guarantee the correctness of your XMLs. Different normative across countries could lead to differences in listing characteristics in terms of mandatory fields and values admitted within the same field.You should double check:• Whether a field is mandatory in the sheet Data Definition of the Excel FlatFile of the given category of the given country.• Which are the valid values of a field in the sheet Valid Values of the Excel FlatFile of the given category of the given country.ExampleYou need to list a Product in the “Food And Beverage” category on the Italian Marketplace using XML.By looking at the FoodAndBeverage XSD you can see the valid values for the tag ProductType<xsd:eleaent nade=”ProdoetType”›<xsd:complexType><xsd:choice></xsd:element>ref=”Food”/></xsd:element>ref=”HouseholdSupplies”/></xsd:element>ref=”Beverages”/></xsd:element>ref=”Hardliquor”/></xsd:element>ref=”AlcoholicBeverages”/></xsd:element>ref=”Wine”/></xsd:element>ref=”Beer”/></xsd:element>ref=”Spirits”/></xsd:choice></xsd:complexType></xsd:element>This list contains all possible values for the <ProductType> tag on the “Food And Beverage” category worldwide. It is possible that some of this values are not available on certain marketplaces.To confirm what ProductType values you can use in the Italian FoodAndBeverage category, you need to look up the ProductType column in the sheet Valid Values of the Italian Flat File Food And Beverages.In this column you will read:
There are the only four <ProductType> values admitted for the Food And Beverages category in the Italian Marketplace.That would mean that if you try create a product via XML in the FoodAndBeverage Category of the Italian Marketplace by using a value not present in this list(e.g. <ProductType><HardLiquor>…</HardLiquor></ProductType>) You will get an error even if this value is present in the XSD.HardLiquor is a valid value for the <ProdcutType> tag globally, but not in Italy, in other Marketplaces.You should map in your database all the Valid Values present in the XSDs, but then surface to your application interface only the valid ones according to the specific Marketplace and Category where your Seller wants to create their listing.Seller ExperienceSellers first select the Marketplace and the category and your application shows the mandatory fields and proposes the right valid values.Referring to the previous example, if the Seller has selected to list a product of the FoodAndBeverage category on the Italian Marketplace, your application should present a dropdown menu for the mandatory item ProductType only with “Beer” “Beverage” “Spirits” and “Wine” as possible selectable values.
Surface Errors
Sellers should be able to fix autonomously as many listing creation errors as possible.You should design your application in order to check always the quality of XMLs submitted to Amazon, especially the XML Product Feed. Errors in the Product Feed can lead to subsequent errors in other feeds, like the impossibility of associating an image to a product since the listing creation failed first.
You should always download and check the FeedProcessingReport, through the getFeedSumbissionResult operation of the Feeds API.Visit this page for details and a diagram to help your design.Your application should always map the Listing Creation errors reported in the FeedProcessingReport and surface them to the Seller interface.Seller ExperienceIf an error occurred while creating Listings, your application clearly shows the error message on the interface as well as the way to fix it. Both of these pieces of information are present in the FeedProcessingReport.The Seller can take action, fix data and resubmit their request. In this you can find information about the most common errors.
Manage barcodes exception
In Order to create a new Product on Amazon, Sellers need to provide a Barcode as StandardProductID.You need to take into consideration three cases:Case 1:The Seller uses the barcodes The Seller must identify each product they want to list with the StandardProductIDThere are only two exceptions to Case 1:Case 2:The Seller sells products manufactured without Barcodes:a. The Seller needs to request an Amazon Barcode exemption for the given brand (e.g. BRAND_ABC )b. If Amazon accepts the request, the Seller will receive an email that states: “Your exemption has been accepted, use PARAMETER_1 to identify your products instead of the StandardProductIdc. If Amazon does not accept the request the Seller will not be anyhow able to list products without StandardProductIDCase 3:The Seller is the producer/brand owner:a. The Seller needs to register their brand to the Amazon Brand Catalogue (e.g.BRAND_XYZ)b. If Amazon accepts the request, the Seller will receive an email that states: “Your brand registration has been accepted, use PARAMETER_2 to identify your products instead of the StandardProductIdc. If Amazon does not accept the request the Seller will not be anyhow able to list products without StandardProductIDIn case 2 and 3 Sellers are entitled to list their product without StandardProductID, therefore your application should be able to manage smoothly these cases, and accept XMLs with a slightly different structure.In case 2.c or 3.c, your application should be able to filter these products and exclude them from the upload to Amazon.Before uploading the Product to Amazon, your application should manage the three cases as followsCase 1:Your application should always require in input the <StandardProductID> and check if it meets the Barcode standards.Also consider whether to integrate an API to verify that the barcode has been properly issued by the BarCode Authority. Amazon does not provide such a functionality; you can use public Internet resources.If there is an error, give Sellers the opportunity to correct the barcode and try again to submit the product.Case 2:The Seller sells products without EAN Codes and they have an exception approved.The Seller will send you the product with:a. <PARAMETER_1> populated and no <StandardProductID> tagb. <Brand> populated with the Brand they specified during the Barcode exemption registration process
See the following snapshot where PARAMETER_1 is the <MfrPartNumber> and <Brand> is BRAND_ABC <Message><MessageID>180</MessageID> <OperationType>Update</OperationType><Product><SKU>0012946</SKU><Condition><ConditionType>New</ConditionType></Condition><DescriptionData><Title>TITLE</Title><Brand>BRAND_ABC</Brand><Description>Product …</Description><MfrPartNumber>0012946</MfrPartNumber><SearchTerms>DONNA</SearchTerms><SearchTerms>CASUAL DONNA</SearchTerms><SearchTerms>IGI&CO</SearchTerms><SearchTerms>57712</SearchTerms><SearchTerms>Scarpe donna visone</SearchTerms><ItemType>shoes</ItemType><RecommendedBrowseNode>700832031</RecommendedBrowseNode></DescriptionData><ProductData><Shoes> <ClothingType>Shoes</ClothingType><VariationData><Parentage>parent</Parentage><VariationTheme>Size</VariationTheme></VariationData><ClassificationData><ColorMap>gray</ColorMap><Cepartment>Donna</Department><ModelNumber>57712</ModelNumber> <Season>P/E 2016</Season><TargetGender>female</TargetGender></ClassificationData></Shoes></ProductData></Product></Message>Case 3:The Seller does not have the Barcodes since they are the producer/brand owner The Seller will send you the product witha. <PARAMETER_2> populated and no <StandardProductID> tagb. <Brand> populated with the Brand they required during the Barcode exemption registration processc. You need to add the tag <RegisteredParameter> with value PrivateLabelSee the following snapshot where PARAMETER_2 is the <MFRPartNumber> and <Brand> is BRAND_XYZ<Message><MessagelD>2</MessagelD><OperationType>Update</OperationType><Product> <SKU>609119_19447</SKU><Condition><ConditionType>New</ConditionType></Condition><pescriptionuata><Title>Poster AudreY</Title><Brand>BRAD ;07</Brand><Designer> Famous When Dead</Designer><Description>—Description><Manufacturer>POSTERLOUNGE</Manufacturer>afrParttiSer>609119_19447<hdrPartinober> <IsGiftWrapAvailable>false</IsGiftWrapAvailable><IsGiftMessageAvailable>false</IsGiftMessageAvailable><RecommendedBrowseNode>4606042031</RecommendedBrowseNode> <RecommendedBrowseNode>731704031</RecommendedBrowseNode></DescriptionData><ProductData><Home><ProductType><FurnitureAndDecor><Material>Stampa su tela</Material></FurnitureAndDecor></ProductType></Home></ProductData><RegisteredParameter>PrivateLabel</RegisteredParameter></Product></Message>To manage Case 2 and Case 3, your application should offer a “Barcode exemption/Brand Register” configuration capability to let the Seller configure for which brands they received EAN exemption/GCID. According to the configuration, your application should enable/disable the related mandatory/optional fields in the user Interface to create proper XMLs.Seller ExperienceCase 1:The Seller should input in your interface the Barcode and get an error whenever it does not meet the standard or it is not valid.Case 2:The Seller should be able to configure in your application those Brands for which they have obtained Barcode exemption in the email they received from Amazon.For these brands, the Seller will use PARAMETER_1 to identify the Product (not the StandardProductID).Case 3:The Seller should be able to configure in your application those Brands for which they have obtained GCID as they received in the email they received from Amazon.For these brands, the Seller will use PARAMETER_2 to identify the Product (not the StandardProductID).
Check image quality
Images must meet quality requirementsYou should always check the quality of the images provided by the Sellers. Images must be publicly accessible on the Internet and your solution must feed Amazon systems with only their URLs.Sellers must provide your solution with images that meet the Amazon quality criteria.We suggest you to implement a preliminary control of the images in your application to check the technical parameters (File type, Size, Dimension Resolution) and present an error when quality is not met, before submitting the Image feed to Amazon. Visit the style guide for details.Your application should be capable of detecting these records with defective images and excluding the related SKUs also from the other XML feeds until the Seller fixes the issue.Seller ExperienceIf the Seller creates a listing with an image that does not meet the Amazon quality criteria, they will receive an error on the interface that explains what criteria is not met and an invite to change the image and re-submit the request.
Manage Variations
Products within the same family must be consistentIn case of Variations (Relationship between Parent and Children element), the parent SKU must be considered only a logical element for grouping children, it should not have specific attributes like size, color, price, or quantity and is not buyable.In order to establish a relationship of variation between two products you should:• Define in the Product Feed which SKUs are parents and which are children, populating the <parentage> tag• Define in the Relationship Feed which SKU is child of which parent SKUAn important element to create variations is <VariationTheme> that describes the parameter(s) by which the parent product may vary, mostly used to categorize clothing varying by Size and Color. Check the Flat File for the right valid values of variation theme, according to the Marketplace where you want to list.
|
Variation theme |
Product Attributes |
|
Color |
ColorName |
|
Size |
SizeName |
|
ColorSize or SizeColor |
ColorName and Size Name |
The value input for <VariationTheme> must be the same for both the parent and child SKUs.NB: it is sufficient an error of one of the SKUs of the family and this will prevent the creation of the entire family.Example of a Parent Clothing Product Feed<Message><MessagelD>1</MessagelD><OperationType>Update</OperationType><Product><SKU>83P60021R05835</SKU><DescriptionData><Title>01tre: Trench Woman. </Title><Brand>01tre</Brand><Description>ShortTrench….</Description><BulletPoint>Zip…</BulletPoint><SearchTerms>Trench</SearchTerms><RecommendedBrowseNode>2893123031<1RecommendedBrowseNode></DescriptionData><ProductData><Clothing><VariationData><Parentage>parent</Parentage>aariationThemenneColor</varlationTheme></VariationData><ClassificationData><ClothingType>Outerwear</ClothingType><Department>Woman</Department><StyleKeywords>Apparel</StyleKeywords><MaterialComposition>1004poliesther</MaterialComposition><OuterMaterial>syntetic</OuterMaterial> <OccasionAndLifestyle>Casual</OccasionAndLifestyle><Season>Spring/Summer 2016</Season><IsAdultProduct>false</IsAdultProduct><CollectionName>Pring/Summer 2016</CollectionName></ClassificationData></Clothing></ProductData></Product></Message>
Example of a Child Clothing Product Feed
<Message><MessagelD>2</MessagelD><OperationType>Update</OperationType> <Product><SKU>83260021R05835_02_3</SKU><StandardProductID><Type>EAN</Type><Value>8300736338883</Value></StandardProductID><DescriptionData><Title> Oltre: Trench Woman. Black, Size 42</Title> <Brand>01tre</Brand> <Description>Trench corto doppio petto. Taschine chiuse con bottoni e polsini regolabili da cinturino. Fodera interne a righe.</Description><BulletPoint>Chiusura doppiopetto con bottoni in tinta</BulletPoint> <SearchTerms>Abbigliamento donna</SearchTerms> <RecommendedBrowseNode>2893123031</RecommendedBrowseNode> </DescriptionData><ProductData><Clothing><VariationData>Oarentage>child</Parentage><Bize>42</Size><Color>beige</Color>araziationTheme>SizeColor</variationTheme></VariationData><ClassificationData><ClothingType>Outerwear</ClothingType><Department>Woman</Department><StyleKeywords>Apparel</StyleKeywords><ColorMap>beige</ColorMap><MAterialComposition>100% poliesther</MaterialComposition><OuterMaterial>sintetico</OuterMaterial><OccasionAndLifestyle>Casual</OccasionAndLifestyle><Season>Spring/Summer 2016</Season><SizeMap>42</SizeMap><CollectionName>Spring/Summer 2016</CollectionName></ClassificationData></Clothing></ProductData></Product></Message>
Example of their relationship feed.Note that you should create one message for each children SKU and not one message for the entire family.
<Message><MessageID>l</MessageID><OperationType>Update</OperationType><Relationship> <ParentSKU>83P60021R05835</ParentSKU><Relation> <SKU>83260021R05835_02_30SKU><Type>Variation</Type></Relation></Relationship></Message><Message><MessagelD>2</MessagelD><OperationType>Update</OperationType><Relationship><ParentSKU>83260021R05835</ParentSKU><Relation><sKu>83r60021R05835_02_4</sRn><Type>Variation</Type></Relation></Relationship></Message>
Drive data quality
High-quality categorization data will benefit the product searchabilityYour application should permit your Sellers to input as much information as possible to improve searchability and guarantee the best search experience for the Customer.Browse nodes & Refinements:A Browse node is a code that identifies to which node of the Amazon category tree a product is associated.Your application should map each product to the leaf node of the Amazon catalogue tree in order to guarantee the most accurate association.We suggest you to implement a Browse node association functionality by using the XML BrosweTreeReport downloadable via Reports API. In this way, you will be able to surface to the interface of your application the Categories and Subcategories present in the report and guide your user to Select automatically the right Browse nodes.Alternatively, you can consider mapping the browse nodes in your application by importing the report in Excel format, known as the Browse Tree Guide.For each Browse node, Amazon suggests certain Refinements, specific category attributes that will furthermore increase the searchability of the product.Your application should be capable to surface these fields depending on the selected Browse node and invite your users to populate those attributes.TitlesIt is highly recommended that product titles follow the Amazon style guidelines according to your product category. You should implement a logic in your application that creates and validates titles by concatenating the user input.
Bullet pointsA bullet point is a brief descriptive free text, called out via a bullet point, regarding a specific aspect of the product.You should give Sellers the possibility to include up to five bullet points into your interface to let them specify this information. Note that according to the ProductType certain bullet points can be added automatically.Search TermsA Search Term is a word or phrase that best describes the product.This will help Amazon locate the product when customers perform searches on the site.You should give Sellers the possibility to include up to five search terms into your interface to let your user specify this information.It is highly recommended that product titles follow the Amazon style guidelines according to your product category.
Seller ExperienceFollowing an example of a Seller who wants to list a bottle of Champagne on the UK Marketplace.The application permits the Seller to select in sequence the following categories:
Grocery/BeerWine & Spirits/Sparkling Wine & ChampagneChampagne and the applicationThe application shows and associates the browse node 359889031.
The uses inserts:SKUBarcodeTitleBrandDescription2 out of the 5 possible Search Terms1 bullet point.But can also select two refinements from dropdown menus:
Color (the users selects “white wine”) Sweeteness (the user selects “extra brut”)On confirmation the Product XML should look like the following<Message><MessagelD>1</MessagelD><OperationType>Update</OperationType><Product> <SKU>SKU XXXX</SKU><StandardProductlD><Type>EAN</Type><Value>XXXXXXXXXXXXX</Value></StandardProductlD><LaunchDate>2016-05-02T00:00:00</LaunchDate><conaltion><ConditionType>New</ConditionType></Condition><DescriptionData><Title>Champagne Imperial Brut Gift Boxed 75 cl</Title><Brand>Imperial Brut</Brand> <Description>Founded in 1743, Imperial….</Description><BulletPcint>a fresh crisp palate reveals white-fleshed fruits…</BulletPcint><Manufacturer>Imperial Brut</Manufacturer><SearchVerms>Wine</SearchVerma><SearchTeranChaspagne</SearchTerms><RecommendedBrowseNode>359892031</RecommendedBrowseNode></DescriptionData><ProductData><FoodAndBeverages><ProductType><Food><Wodypeacription>white wine<Modypescription><Tastepeacription>extra brut<flasteDescriptica><DisplayVolume unit0fMeasure=”liter”>0.75</DisplayVolume></Food> </ProductType></FoodAndBeverages></ProductData></Product></Message>
Match against existing products
Amazon does not allow duplicates products on the catalogue.Your application should implement a logic to manage smoothly product mismatching edge cases.When a Seller creates a new listing for a product already present on Amazon, but provides a key attribute of that product different than the one already on the Amazon catalogue, you will get an error code 8541 or 8542 in the processing report. These errors are also known as matching errors.Your application should be able to parse the processing report, detecting matching errors and propose an interface to the Seller, highlighting these conflicts of information.
You can also consider implementing an additional functionality to highlight in advance to the Seller any potential matching conflict by retrieving all the information of an existing product through the Products API.
NB: You can force the matching by retrieving the ASIN code from the Product API and create the listing using that ASIN as <StandardProductID>.
While this easy listing practice works in the majority of cases, we suggest not do proceed like this since it could ultimately create in the Seller’s catalogue a different product than the expected one (e.g. when the Seller provides a valid EAN code, but of a different product).
In this case we suggest you at least to surface to the application interface the product you are about to match and let your user confirm that it is exactly the product for which they want to create a listing. If the product API returns more than one ASIN for a single barcode, we suggest you to surface the item with the lowest <rank> value.
Seller Experience:The Seller submits a new listing and, on feed submission termination, the application informs whether one or more attributes they provided conflict with the Amazon catalogue, highlighting them and proposing the value present on Amazon.
The application gives the Seller the possibility to fix the issues and re-submit the product.
Should the Seller be sure of the correctness of their data, conflicting with the data on Amazon, the application refers them to cut a ticket to Seller Support to require an adjustment of the Amazon catalogue.– Only if your application implements the preliminary check –
When the Seller inserts the EAN code, the application displays all the information of that Product in case it is already on the Amazon catalogue. The Seller only confirms they want to add their offer to that product.
amazon services Europe Listing Creation – amazon services Europe Listing Creation –
[xyz-ips snippet=”download-snippet”]