SUMMARY
🎥 Amazon V2: Let’s talk about it live!
Join our dedicated webinar to discover in 30 minutes what’s changing, how to migrate smoothly, and ask your questions live.
📅 Join us on Monday, May 19 at 11 AM
1. General information
Amazon has made some changes in their API, which include the depreciation of XML files for listing publications. Because of this, BeezUP must migrate to the JSON-based files for the publication process.
We decided to use this opportunity to create a new channel with all of our V.2 functionalities, and well as some nice surprises 😉
Dynamic attributes mapping according to your product types (categories).
Value mapping for attributes.
Technical errors report + business errors report.
Single channel by country - no more universes!
Publication types will now be aligned with most of our other marketplaces: only product and offers.
V.1 Amazon | V.2 Amazon | Frequency | Strategy |
Products Images Relationship |
Products |
24h |
Full |
Price
Inventory |
Offers |
Dynamic* | 1h* | 2h | Differential + unpublish |
* Dynamic and 1h offer publications are only available for some BeezUP plans. Please contact our customer service if you want to know more.
ℹ️ For more information about the dynamic attributes and values mapping, please look at our dedicated documentation: Channel V2: all you need to know.
ℹ️ For more details about the Amazon API change, please visit the Amazon site here.
a. Important Amazon definitions
📘 Product types: Amazon categories are linked to product types, and each product type has specific attribute and data requirements. In the new V.2 channel, you will see the product types in the last level of the category mapping:
We will use the product type to show you only the relevant attributes for your products in the columns mapping page.
📘 Patch mode: Amazon has two publication modes that are set at product level : "update" and "patch".
By default, BeezUP sends all products in update mode, which will automatically replace the information if Amazon accepts the listing (no errors). However, you can choose to activate the patch mode for any or all products if you only wish to update the information being sent, without affecting not sent attributes. This is the equivalent of the partial update mode in the V.1 channel.
To activate it, you must send the value True in the Patch Mode field found in the column mapping.
You can use a custom field to determine which products to send in patch mode.
📘 Amazon universes: The V.2 channel can publish products for all categories, as well as products that have already been created on Amazon (EAN matching as used in Amazon Direct (V.1)).
📘 Technical errors: We use the term technical error for errors returned by Amazon when the data sent does not correspond to the Amazon schema. This could be, required attributes that are missing, or sent values with the incorrect data type (e.g., a string was sent for an integer attribute).
📘 Business errors: We use the term business error for issues regarding the content of the information sent or the status of your account. An attribute can have the correct data type, but Amazon might refuse it, or they might request for authorizations before listing products from certain brands. They could also reject listings because of reasons related to your account status.
b. Amazon deadline for the migration
📅 Amazon has set the removal date for the XML feeds for June 30, 2025.
⚠️ You have until then to migrate to the V.2 channel if you don't want any interruption in your publications.
2. Business report page
With the new JSON feeds, comes a change in the Amazon publication report.
Reports from publications with XML feeds (Amazon V.1) contain both technical and business errors, however, reports from JSON feeds (Amazon V.2) only contain technical errors.
Once a product has no error in the product publication report, you can consider it was accepted from a technical point of view. Now, Amazon might take up to 8 hours to process this product.
If Amazon rejects the product, you will see the related business error in our new page Business errors.
This new page is available on the Publications and Product Vision pages.
The mismatch (8541/8542 error codes) errors will be visible in this new page, and you will still be able to set products as identical to accept the Amazon ASIN suggestion in order to fix this error.
📢 It is now possible to mark all mismatch errors as accepted with only one click!
3. Migration to V.2: steps to follow
1. Add the Amazon V.2 channel for your country.
2. Map your categories in the Category Mapping page. Please note that the category tree has been updated, so it will not be possible to copy the category mapping from the V.1 to V.2. If you use Amazon Direct or you only send offer updates, please follow these steps.
3. Go to the Column Mapping page and map at least all required attributes. If you have questions on the new attributes, please check the descriptions found next to each attribute and see this section for the list of most common attributes.
4. If you had exclusion conditions in the V1 channel(s), please replicate the same conditions in the new Amazon V.2 channel.
5. Now you can recover your API token from the API Settings page and select the countries you want to recover orders from (you can go to the API Settings of the V.1 channel to see your current configuration). No need to activate any publication type for now.
6. Activate the Amazon V.2 channel - while leaving the V.1 channel(s) active.
a. Orders
There will be no impact for the order recovery and order status change. Once you activate the Amazon V.2 channel, the order recovery will be done as usual.
Whether you change the status with the use of our module, directly in the BeezUP page or by API, your current process will remain the same. No changes to be done on your side.
⚠️ Just pay attention to the countries selected in the V.1 Amazon channel so you can have the same configuration.
b. Offer publication
We recommend you start by migrating the offers publications.
Map at least the attributes mentioned here and activate offer publication in the API Settings page for Amazon V.2 channel.
Then wait for the first automatic offer publication: If you see errors in offer publication, check the report and map the necessary fields or correct the mapped values (some attributes have a list of valid values).
Once you see no errors in offer publication, congratulations 🎉.
You can now deactivate inventory and pricing publications in V.1 channel(s).
ℹ️ All active SKUs will be sent in the first offer publication of the Amazon V.2 channel.
c. Product publication
After activating the offer publication, you can start migrating product publications.
Map at least the attributes mentioned here and here if you have variations. Then deactivate the product, images and relationship publications in the V.1 channel(s).
You can now activate product publication in the API Settings page for the Amazon V.2 channel.
Wait for the first automatic product publication: If you see technical errors in the product publication, check the report and map the necessary fields or correct the mapped values (some attributes have a list of valid values). See here for more information on these technical errors.
Once you see no technical errors in the product publication report, congratulations 🎉.
7. Once you have successfully activated both publication type in the V.2 channel by following the steps above, you are all set 🙌. Please deactivate V.1 channel(s).
4. FAQ
a. Amazon Direct > Amazon V.2
Amazon Direct is a V.1 channel that lets you publish products that already exist on Amazon database. It uses the ASIN number (Amazon Standard Identification Number) to attach your SKU to the Amazon data sheet, with minimal effort (no categorization and no specific attributes mapping).
In order to publish these products with Amazon V.2 using the same approach, you need to categorize all products to the “Amazon Direct” category.
☑️ Tip: Use the All Categories section to map all categories at once.
By categorizing products with Amazon Direct, the columns mapping page will show you the minimum required attributes you need to map, similar to the V.1 channel.
b. How to set up product variations?
Amazon requires you to create a data sheet for the “parent” product and then attach all variation product sheets to said parent.
Follow the next table to map (or not) the required attributes to create a variation:
Attribute name | Parent | Variation (child) |
Sku | ✔️ | ✔️ |
Externally assigned product identifier > Value | ❌ | ✔️ |
Externally assigned product identifier > Type | ❌ | ✔️ |
Child parent sku relationship > Parent sku | ❌ | ✔️ |
Child parent sku relationship > Child relationship type | ✔️ | ✔️ |
Parentage level | ✔️ | ✔️ |
Variation theme > Name | ✔️ | ✔️ |
fields related to the variation theme, e.g. Color > Value | ❌ | ✔️ |
Here is an example:
Attribute name | Parent | Variation (child) |
Sku | ABC | ABC_123 |
Externally assigned product identifier > Value |
| 0000123456789 |
Externally assigned product identifier > Type |
| ean |
Child parent sku relationship > Parent sku |
| ABC |
Child parent sku relationship > Child relationship type | variation | variation |
Parentage level | parent | child |
Variation theme > Name | COLOR_NAME | COLOR_NAME |
Color > Value |
| blue |
ℹ️ For more information on variation products, please visit our dedicated documentation: Products with parents/children variations relationships | BeezUP Help Center
c. Most commonly necessary attributes
Product attributes
Product attributes
Amazon V.1 | Amazon V.2 |
SKU | Sku |
EAN | Externally assigned product identifier > Value to be mapped alongside Externally assigned product identifier > Type 🔎 please check the list of valid values |
MfrPartNumber | Part number |
Title | Item name |
Description | Product description |
Brand | Brand |
Manufacturer | Manufacturer |
BulletPoint1 ... BulletPoint5 | Bullet point |
ImageLocation | Main Image |
Additional_image | Additional Image 1 ... Additional Image 8 |
SearchTerms | Generic keyword |
ShippingWeight_in_gr | Item package weight > Value to be mapped alongside Externally assigned product identifier > Type 🔎 please check the list of valid values |
PackageHeight PackageHeightUnitOfMeasure | Item package dimensions > Height > Value to be mapped alongside Item package dimensions > Height > Unit 🔎 please check the list of valid values |
PackageLength PackageLengthUnitOfMeasure | Item package dimensions > Length > Value to be mapped alongside Item package dimensions > Length > Unit 🔎 please check the list of valid values |
PackageWidth PackageWidthUnitOfMeasure | Item package dimensions > Width > Value to be mapped alongside Item package dimensions > Width > Unit 🔎 please check the list of valid values |
Weight WeightUnitOfMeasure | Item weight > Value to be mapped alongside Item weight > Unit 🔎 please check the list of valid values |
Height HeightUnitOfMeasure | Item depth width height > Height > Value to be mapped alongside Item depth width height > Height > Unit 🔎 please check the list of valid values |
Depth DepthUnitOfMeasure | Item depth width height > Depth > Value to be mapped alongside Item depth width height > Depth > Unit 🔎 please check the list of valid values |
Width WidthUnitOfMeasure | Item depth width height > Width > Value to be mapped alongside Item depth width height > Width > Unit 🔎 please check the list of valid values |
Offer attributes
Offer attributes
Amazon V.1 | Amazon V.2 |
SKU | Sku |
StandardPrice | Standard Price |
Saleprice StartDate EndDate | Discounted Price to be mapped alongside Price Sale Start Date Price Sale End Date |
Condition | Condition type 🔎 please check the list of valid values |
MerchantShippingGroupName | Merchant shipping group |
MSRPWithTax | List price > Value with tax |
FulfillmentCenterID | Fulfillment CenterID 🔎 please check the list of valid values |
FulfillmentLatency | Fulfillment Latency |
Quantity | Quantity |
d. Requirement level vs. publication errors
You may notice in the product publication report that some attributes appear to be mandatory, however, they are not marked as mandatory in the mapping page.
Please note that we mark attributes as mandatory if they are also marked this way in the Amazon schema for the specified product type.
However, Amazon also applies conditional requirement: an attribute might become mandatory if you map a specific value in an attribute or group of attributes. We do not show these conditional requirements in the mapping page.
⚠️ Please monitor your product publications, as some attributes marked as optional in the mapping might be mandatory depending on the information you are sending.
e. Publications in error
If you launch publications just after activating the Amazon V.2 channel, they may be in error.
There are actions done automatically after activation that take a few minutes, so it is normal to see the publications in error when you launch them.
Note that we recommend you to wait for automatic publications rather than manually launch the publications during the migration to V.2.