Amazon SP API Taxonomy

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)

Amazon Catalog is very complex: the taxonomy is very deep, for each category there are a lot of different attributes and each of this attribute is of a different type (e.g string, numbers, selections and so on). Some of these attributes are required, while some others are required if a value for a set of a group of a particular attributes has been specified. Consider that all of these rules can change market by market (i.e. it may work in a way in Amazon Italy, while in a totally different way in Amazon US).This complexity can be handled, thanks to Amazon’s new SP-API, by integrating with the shining new powerful **Product Type Definitions API**

Basically, Amazon defines a set of informations per each product type. A product type is, as these words suggest, a particular type of product. A lot of product types are available in the Amazon Taxonomy and a lot are added day by day. Amazon product types work in a hierarchical way: each product type inherits from a common base product type which is called PRODUCT. And, in order to push an offer for an existing product, we must adhere to that product type. If we want to list a brand new product which does not exist on Amazon’s catalogue, we need to validate against the json schema for the productType based on the category we are trying to list. We could look at the product type as a category. Every product type is described through a JSON schema  and every request made to Amazon must validate against that practicular schema. 

Get Product Types

This is the first call we need to make in order to receive all product types based on the marketplace region.

API Call: GET /definitions/2020-09-01/productTypes API Docs : https://developer-docs.amazon.com/sp-api/docs/product-type-definitions-api-v2020-09-01-reference#getdefinitionsproducttype

Usage Plans:

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above.

Parameters

Mapping :

Example response :

{
    "productTypes": [
        {
            "name": "3D_PRINTABLE_DESIGNS",
            "displayName": "3D_PRINTABLE_DESIGNS",
            "marketplaceIds": [
                "A1F83G8C2ARO7P"
            ]
        },
        {
            "name": "3D_PRINTED_PRODUCT",
            "displayName": "3D_PRINTED_PRODUCT",
            "marketplaceIds": [
                "A1F83G8C2ARO7P"
            ]
        },
        {
            "name": "3D_PRINTER",
            "displayName": "3D Printer",
            "marketplaceIds": [
                "A1F83G8C2ARO7P"
            ]
        },
        {
            "name": "ABDOMINAL_EXERCISER",
            "displayName": "Abdominal Exerciser",
            "marketplaceIds": [
                "A1F83G8C2ARO7P"
            ]
        }
    ],
    "productTypeVersion": "UAAAAAAAAAAAAAAAAlYD1uY6w8U34BeTFZ_qsvR28sg0="
}

Please note that this response has been modified to show just a few categories as the full response is too big, the full one can be found here :

response3.json

Once we have received all the available productTypes (categories) we need to call each category and retrieve the specific JSON schema for the specific category :

Get Product Type Definitions

API Call : GET /definitions/2020-09-01/productTypes/{productType}

API Docs : https://developer-docs.amazon.com/sp-api/docs/product-type-definitions-api-v2020-09-01-reference#getdefinitionsproducttype

Usage plan is the same as the previous call.

Parameters

Mapping :

Example response :

{
    "metaSchema": {
        "link": {
            "resource": "https://selling-partner-definitions-prod-dub.s3.eu-west-1.amazonaws.com/schema/amazon-product-type-definition-meta-schema-v1.json/rZ%252F2Yep0np022S38ZdEiNQ%253D%253D?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJHMEUCIQDudOyxrX984NCpYhnlVGEJOAGZwmChdH6GNL%2BMXutnUwIgL0%2Bk6k6H12lCZU2dlngj4QmYHVJopzrc5pdEbsE3C94qyQQIQBADGgw1MzU3ODk4MjM4MDgiDArH%2FAdavtR4Ognu0CqmBEJCGIK%2FXy8rINGXCDO8HWCYEXLGLOA8b2Xp9YhXDs1UyJJIgG%2FoDmJbAEgDhq9Q%2FUEzsFz7j72VYTNYK%2F3aFVa1ZZQg7Pnbva7oaeKwBWDPc4oZV70UGzEHW9J106JlTWnM96FlfWtkiUkoXIunJQCh450p3KYrkuBKzmwhGLEA6oA81s%2Bx5qA0OWH15WmphY8BPThlZNgq1AOWIhQ%2FtTRkBgoaWJNqzJQ8Z27xMtjvAY8st5%2B7f6R%2B%2BqFfx8BBkrtnknUC5bAws8lA4kpnI76%2BxTU8a5Zu%2FJbuuOaL%2FFGXy0Zv2RXKtCCmcEOxCcgium7Xgn%2BYNYliTGuzyNbldKntWNU7BaaWPy6tM0dv1vrS%2Bi7C8O6ABx1Bwu%2BD0Hk27HkxIpF0QsHEr5D%2FP4wMLbVi7u2znkn7DRqdHT8a9d8fPEOUMnjUEFcwnhDuUF1iLIR9luhaot8CMBHgPlebqfkEFZS%2FQAtXG0WPLkLc1Iwu24flHeSgtdieaVssXCnWWzJg9Gqr0srmNNwmbiUkqF7M%2F9Kqp%2FKRXlEFuWlcUHQHvCD9xmpyL9CTZreiaySOrGVezQgXvcnsLZNwOYlgQsNp6t5M%2F8no0KVpE%2BvxiiM6ypEnTCgW086juqh8RwktwmKJx89p193m3LoUyjvrfiE42Zgp1WN3dDvg%2F7mJngn6bk50wm6jOJ7xLWVRn4B1yIb9CqpiolFF%2F3Dbak2gY5Mw1scK0%2Bow3cmaswY6pwFvIGpgezyVLY3QHIpjbLrYb%2BLHhGV7y7s27zkcxD2I4W8G3reDcm%2FBciQuEuA%2BWBZzZw0PXIQBlRCJG3g6OCIVkzU9QpkuSbk9mXss5Dpg%2BBGGOr%2FHKn7Kmt7XvF6MY%2BiIKs8gi3PEpEOg2ShJBP7gxBlgRYzBjir7VfEhnvkLlQcA2vlzHTnXa%2FaOgDfZDcOUCwmDbKQmpm9Vx34NNAUe84wtnR18pA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240610T085611Z&X-Amz-SignedHeaders=host&X-Amz-Credential=ASIAXZP4P45AFZEIP73T%2F20240610%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=529dba34ffefdb37356229fe683aef0241ae836f7bcc9fdb2dfac92b268dc865",
            "verb": "GET"
        },
        "checksum": "rZ/2Yep0np022S38ZdEiNQ=="
    },
    "schema": {
        "link": {
            "resource": "https://selling-partner-definitions-prod-dub.s3.eu-west-1.amazonaws.com/schema/3D_PRINTABLE_DESIGNS.json/tzUzTBORc7OwhIMiz9LuDg%253D%253D?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCWV1LXdlc3QtMSJHMEUCIQDudOyxrX984NCpYhnlVGEJOAGZwmChdH6GNL%2BMXutnUwIgL0%2Bk6k6H12lCZU2dlngj4QmYHVJopzrc5pdEbsE3C94qyQQIQBADGgw1MzU3ODk4MjM4MDgiDArH%2FAdavtR4Ognu0CqmBEJCGIK%2FXy8rINGXCDO8HWCYEXLGLOA8b2Xp9YhXDs1UyJJIgG%2FoDmJbAEgDhq9Q%2FUEzsFz7j72VYTNYK%2F3aFVa1ZZQg7Pnbva7oaeKwBWDPc4oZV70UGzEHW9J106JlTWnM96FlfWtkiUkoXIunJQCh450p3KYrkuBKzmwhGLEA6oA81s%2Bx5qA0OWH15WmphY8BPThlZNgq1AOWIhQ%2FtTRkBgoaWJNqzJQ8Z27xMtjvAY8st5%2B7f6R%2B%2BqFfx8BBkrtnknUC5bAws8lA4kpnI76%2BxTU8a5Zu%2FJbuuOaL%2FFGXy0Zv2RXKtCCmcEOxCcgium7Xgn%2BYNYliTGuzyNbldKntWNU7BaaWPy6tM0dv1vrS%2Bi7C8O6ABx1Bwu%2BD0Hk27HkxIpF0QsHEr5D%2FP4wMLbVi7u2znkn7DRqdHT8a9d8fPEOUMnjUEFcwnhDuUF1iLIR9luhaot8CMBHgPlebqfkEFZS%2FQAtXG0WPLkLc1Iwu24flHeSgtdieaVssXCnWWzJg9Gqr0srmNNwmbiUkqF7M%2F9Kqp%2FKRXlEFuWlcUHQHvCD9xmpyL9CTZreiaySOrGVezQgXvcnsLZNwOYlgQsNp6t5M%2F8no0KVpE%2BvxiiM6ypEnTCgW086juqh8RwktwmKJx89p193m3LoUyjvrfiE42Zgp1WN3dDvg%2F7mJngn6bk50wm6jOJ7xLWVRn4B1yIb9CqpiolFF%2F3Dbak2gY5Mw1scK0%2Bow3cmaswY6pwFvIGpgezyVLY3QHIpjbLrYb%2BLHhGV7y7s27zkcxD2I4W8G3reDcm%2FBciQuEuA%2BWBZzZw0PXIQBlRCJG3g6OCIVkzU9QpkuSbk9mXss5Dpg%2BBGGOr%2FHKn7Kmt7XvF6MY%2BiIKs8gi3PEpEOg2ShJBP7gxBlgRYzBjir7VfEhnvkLlQcA2vlzHTnXa%2FaOgDfZDcOUCwmDbKQmpm9Vx34NNAUe84wtnR18pA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240610T085611Z&X-Amz-SignedHeaders=host&X-Amz-Credential=ASIAXZP4P45AFZEIP73T%2F20240610%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=507102501c75392a74ee7a50d8b394204809a60eebc8f5a39803d8182a6f1c41",
            "verb": "GET"
        },
        "checksum": "tzUzTBORc7OwhIMiz9LuDg=="
    },
    "requirements": "LISTING_OFFER_ONLY",
    "requirementsEnforced": "ENFORCED",
    "propertyGroups": {
        "offer": {
            "title": "Offer",
            "description": "",
            "propertyNames": [
                "skip_offer",
                "fulfillment_availability",
                "map_policy",
                "purchasable_offer",
                "condition_type",
                "condition_note",
                "product_tax_code",
                "merchant_release_date",
                "merchant_shipping_group",
                "max_order_quantity",
                "gift_options",
                "main_offer_image_locator",
                "other_offer_image_locator_1",
                "other_offer_image_locator_2",
                "other_offer_image_locator_3",
                "other_offer_image_locator_4",
                "other_offer_image_locator_5"
            ]
        },
        "shipping": {
            "title": "Shipping",
            "description": "Shipping",
            "propertyNames": [
                "item_dimensions",
                "item_package_dimensions"
            ]
        },
        "safety_and_compliance": {
            "title": "Safety & Compliance",
            "description": "Safety and compliance",
            "propertyNames": [
                "country_of_origin",
                "batteries_required",
                "batteries_included",
                "battery",
                "num_batteries",
                "number_of_lithium_metal_cells",
                "number_of_lithium_ion_cells",
                "lithium_battery",
                "supplier_declared_dg_hz_regulation",
                "ghs",
                "hazmat",
                "safety_data_sheet_url",
                "item_weight"
            ]
        },
        "product_identity": {
            "title": "Product Identity",
            "description": "Product identity",
            "propertyNames": [
                "externally_assigned_product_identifier",
                "merchant_suggested_asin"
            ]
        }
    },
    "locale": "en_GB",
    "marketplaceIds": [
        "A1F83G8C2ARO7P"
    ],
    "productType": "3D_PRINTABLE_DESIGNS",
    "displayName": "3D_PRINTABLE_DESIGNS",
    "productTypeVersion": {
        "version": "UAAAAAAAAAAAAAAAAlYD1uY6w9kQTGOwFE1USxW3YJ04=",
        "latest": true,
        "releaseCandidate": false
    }
}

Once we have the response we need to obtain the actual schema by making a GET call to the value in the schema>link>resource property, which is a link that contains the actual requested JSON Schema.

Just make a GET request to the URL contained inside the schema>link>resource. Beware: the generated link lasts for 7 days, so we will need to refresh it every 7 days. Note : After testing it turns out that the link might be active for 7 days but the token expires way faster (around 12 hours) so we need to implement additional logic on that.

The schema is too long to be pasted so please find attached

SCHEMA_UPDATED.json

Some important things:

• arrays may contain objects and, in this case, at least all the required properties for the contained object type must be specified
• string types can be free text and/or enum (i.e. the value must be selected from a list of valid values). In order to understand if it is a freetext or not, check the allOf property of the type definition
• beware: sometimes string values are required but the minimum length should be equal to 0 characters. This means that you need to pass a value in order for the JSON to be valid, but this value can also be an empty string (e.g. check the bullet_point type definition)
• beware: in some cases, properties have multiple levels. For example the battery property contains cell_composition and weight properties. The first defines just a value property, while the latter defines unit and value

Wherever we have properties with multiple levels which include unit and value we need to be able to choose the unit that we are sending the corresponding value for. So if we take the above example with battery and its weight property, we want to be able to input this in Item Specifics in the following format : Battery>Weight>Unit which will be grams,kilograms etc, and Battery>Weight>Value which will be the actual value. We want to include this for all properties that are on multiple levels.

Once we have checked all schemas, we could see that there are some “root” attributes which are the same for every category and can be sent with every product category. Below you can find the root attributes and mapping in Hemi. For different categories, different root attributes will be required based on the schema.

AND Product > Length AND Product > Width OR Product Account > Item Specifics | We pick Item Specifics with priority.

If we pick from Product we need to convert in inches. The format that need to be sent is : “Height x Length x Width inches” Example : ”10 x 2 x 2.7 inches”

We still expect the values to be in CM | | product_description | Product Account > Description | | | brand | Product > Brand OR Product Account Item Specifics > Brand | Item Specifics is with priority | | bullet_point | Product Account Amazon > Bullet Points | New field in Product Account Amazon
By default there should be only one row, but we want to have a button “add row” so we can add more rows if needed (just like More Picture URLs field) | | quantity | Product Account > Quantity | This is a property of fulfillment_availability array | | condition_type | Product > ConditionID | We need to create mapping : New (with tags) > new_new Manufacturer refurbished > refurbished_refurbished Seller refurbished > refurbished_refurbished Used (Pre-owned, Like new) > used_like_new Very Good > used_very_good Good > used_good Acceptable > used_acceptable Like New > used_like_new Refurbished acceptable > refurbished_refurbished

Any other conditionIds not mentioned above, we want to store an error in Product Account > Update Item Error stating that this condition is not supported by amazon. | | part_number | Product Account Item Specifics > Part Number OR Product > MPN | Item Specifics is with priority | | item_name | Product Account > Title | | | list_price | Product Account > RRP | Provide the list price for the product. List Price is the suggested retail price of a product as provided by a manufacturer, supplier, or seller. This is not the offering or cost price.” | | our_price | Product Account > Price | This is a property of purchasable_offer array | | merchant_suggested_asin | Product Account > ChannelItemID | We will not use this field when creating new product but since the same schemas are used, we need this when updating a product. | | externally_assigned_product_identifier | Product Account > Marketplace EAN OR Product > EAN OR Product > UPC OR Product > GTIN OR Product > ISBN | We should pick Product Account > Marketplace EAN with priority, then Product > EAN, UPC , GTIN and last by priority is ISBN | | recommended_browse_nodes | Product Account Amazon > Recommended Browse Nodes | new field | | purchasable_offer | Product Account > Currency OR Account > Exchange Rate Calculator Currency | Product Account will be with priority but if it is empty we pick from Account | | supplier_declared_dg_hz_regulation | Product Account Amazon > Supplier Declared Dangerous or Hazardous Material | New field. It should be a text field which by default is empty. If the field is left empty, we need to send “not_applicable” when this field is required by a JSON schema. | | main_product_image_locator | Listing Image | Please note that as per the JSON schema we need to send main_product_image_locator = ‘Feed’ BUT inside the main_product_image_locator we have an item which is media_location and this is where we need to send the actual URL of the photo. Image selection is as per the abstraction - Images Handling Additional Explanation | | other_product_image_locator_1 | More Images | Please note that as per the JSON schema we need to send other_product_image_locator_1 = ‘Feed’ BUT inside the other_product_image_locator_1 we have a property which is media_location and this is where we need to send the actual URL of the photo. Image selection is as per the abstraction - Images Handling Additional Explanation | | other_product_image_locator_2 | More Images | Same as above. | | other_product_image_locator_3 | More Images | Same as above. | | other_product_image_locator_4 | More Images | Same as above. | | other_product_image_locator_5 | More Images | Same as above. | | other_product_image_locator_6 | More Images | Same as above. | | other_product_image_locator_7 | More Images | Same as above. | | other_product_image_locator_8 | More Images | Same as above. | | <v1.1> gpsr_manufacturer_reference | Account Amazon >GPSR Manufacturer Email OR Product Account Amazon > GPSR Manufacturer Email | This is not required, so if empty we exclude it from the payload. Product Account Amazon is with priority | | dsa_responsible_party_address | Account Amazon > DSA Responsible Party Email OR Product Account Amazon > DSA Responsible Party Email | This is not required, so if empty we exclude it from the payload. Product Account Amazon is with priority | | gpsr_safety_attestation | Account Amazon > GPSR Safety Attestation OR Product Account Amazon > GPSR Safety Attestation | This should be a dropdown enum field with options of Yes and No . If Yes we send true, if No we send false. Default option should be empty and if empty, we exclude it from the payload. Product Account Amazon is with priority | | content_type | Account Amazon > Compliance Media Type OR Product Account Amazon > Compliance Media Type | Please note that this is part of the compliance_media property in the JSON schema and we need to send either all 3 together or none of these properties. We need to have validation and if one or two are filled but others are missing, we want to return internal error. Product Account Amazon is with priority | | content_language | Account Amazon > Content Language OR Product Account Amazon > Content Language | Please note that this is part of the compliance_media property in the JSON schema and we need to send either all 3 together or none of these properties. We need to have validation and if one or two are filled but others are missing, we want to return internal error. Product Account Amazon is with priority | | source_location | Account Amazon > Media Source Location OR Product Account Amazon > Media Source Location | Please note that this is part of the compliance_media property in the JSON schema and we need to send either all 3 together or none of these properties. We need to have validation and if one or two are filled but others are missing, we want to return internal error. Product Account Amazon is with priority </v1.1> |

Taxonomy export file

In order to generate the taxonomy file we will need to create a new record in Taxonomy export with: Marketplace = Amazon Status = pending Category for Export = all (or we can specify which exact categories) Email = email to which the file will be send

We want to display the title and description of the property in the export file.

We want to have a logic and if the user has selected 5 or more categories for export, we want to export them in a single zip file. This will be valid also if all categories are being exported.

Please find example file structure how it should look like after exported. We store for each category separate file.