Amazon SP API Listing Create

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)

This page will hopefully give good understanding of how the product creation will work on Amazon.

General Information:

• Amazon operates on a catalogue base which means there is a product created in their system and different sellers can create listings against that product. Sellers cannot create their own new products if the same product exists on Amazon.
• Amazon work with unique codes called The Amazon Standard Identification Number (ASIN) which is the equivalent of a Channel Item Id.

There are three main cases that need to be considered when we are talking about “product creation”.

-The first case is when we have a product that is already created in Amazon’s catalogue AND there is an offer (SKU) against this catalogue product in the seller’s Amazon account.

-The second case is when we have a product that is already created in Amazon’s catalogue BUT there is no offer (SKU) against this catalogue product in the seller’s Amazon account.

-The third case is when there is NO product in Amazon’s catalogue and it needs to be created

Below is a diagram which aims to give an overview of the flow structure.

Eventually we want to be able to cover all three cases so we need to implement a logic that will be able to check this. There are different calls for the different cases and all of them will be explained in this document. It is up to the developers to decide whether we want to implement a few checks (this means a few API calls) in one cron or we should split everything into separate crons.

The first step is to check if the SKU we are trying to create is already created in the seller’s account and this is done through the Get Listings Item API:

Get Listings Item

Using this call, we can check if a listing is already created for a specific SKU in our particular seller’s Amazon account. If it exists, we need to mark this in Hemi and do not continue to create the product but instead only send updates.

Our starting point will be our default listing statuses Product Account > Listing Status = Inactive and Product Account > Product status **= Awaiting Creation and Product Account > List/Update the whole Item = Pending

API Call : GET /listings/2021-08-01/items/{sellerId}/{sku}

API Docs: https://developer-docs.amazon.com/sp-api/docs/listings-items-api-v2021-08-01-reference#getlistingsitem

Usage Plan:

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation but based on different sellers the rates might be higher so we need to implement a logic that will abide to the x-amzn-RateLimit-Limit response.

Parameters

As per the above table, we need to include the sellerId, sku, marketplaceIds.

Mapping :

If the product exists in the seller’s account, then we will get the following response :

{
    "sku": "4065452136666",
    "summaries": [
        {
            "marketplaceId": "A1F83G8C2ARO7P",
            "asin": "B0DD79MXNH",
            "productType": "SHOES",
            "conditionType": "new_new",
            "status": [
                "BUYABLE",
                "DISCOVERABLE"
            ],
            "itemName": "PUMA Baby Toddler Unisex One4All Slip On Shoes Size Infant 6 UK",
            "createdDate": "2024-08-15T07:55:05.266Z",
            "lastUpdatedDate": "2024-08-15T07:55:20.405Z",
            "mainImage": {
                "link": "https://m.media-amazon.com/images/I/31w62ArMTrL.jpg",
                "height": 500,
                "width": 500
            }
        }
    ],
    "issues": [
        {
            "code": "18448",
            "message": "Attributes tagged as relevant_attributes are incomplete. Provide values for the following attribute(s): occasion_type, special_feature",
            "severity": "WARNING",
            "attributeNames": [
                "occasion_type",
                "special_feature"
            ],
            "categories": [
                "MISSING_ATTRIBUTE"
            ]
        }
    ]
}

Response mapping :

There will be two cases here: If we receive the ASIN and the productType in the response we want to always store them in Hemi and mark the Product Status = Published.

However if we receive even one issue with severity = “ERROR” we want to set the List/Update The Whole Item = Error but still update the ProductStatus, ChaneItemId and the PrimaryCategoryId.

If there are issues with only severity = “Warning” we set the List/Update The Whole Item = Not Needed and still update the ProductStatus, ChaneItemId and the PrimaryCategoryId. </v1.2> | | | severity | | N/A | | | | attributeNames | | N/A | | | | categories | | N/A | |

We are then to proceed and update the product :

If the product is published then we mark it as published as per the abstraction .- Product Listing general requirements. It will be published if it has severity - Warning or empty in the response .

If the product is not published we set the Product Account > List/Update the Whole Item and the error as per the above mapping, but at the same time we also want to store the channel item id, category and status as we are essentially successfully linked to a product which is created, but not live on amazon and has some error. We also set the Product Account > Product Status = Product Created.

Additionally, we also want to mark the product with Product Account Amazon > Catalogue Exists = Yes (this is a new field, we want to have default value of empty, plus two more statuses - Yes and No)

Since we have no information whether the listing is active on amazon or not (i.e if it has positive quantity) we also want to raise the Product Account > Update Quantity and Product Account > Update Price = Pending and update the Listing Status accordingly.

If the product does not exist in the seller’s account, we will get the following response :

{
    "errors": [
        {
            "code": "NOT_FOUND",
            "message": "SKU '78201215000' not found in marketplace A1F83G8C2ARO7P"
        }
    ]
}

If we receive this response this means that we can proceed and create it. This means we will need to set the Product Account > Product Status = Product not created so we can then proceed and pick it up for creation.

In order to do this, we first need to check if the product we are trying to create SKU against, exists in Amazon’s catalogue. In order to search for a particular product we need use the searchCatalogItems call :

Search Catalog Items

Using this call we can search for and return a list of Amazon catalog items and associated information either by identifier or by keywords.

Our starting point is Product Account > Product Status = Product Not Created AND Product Account Amazon > Catalogue Exists = ‘’ (this is a new field, we want to have default value of empty, plus two more statuses - Yes and No)

API Call : GET ****/catalog/2022-04-01/items

API Docs: https://developer-docs.amazon.com/sp-api/docs/catalog-items-api-v2022-04-01-reference#get-catalog2022-04-01items

Usage Plans:

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation but based on different sellers the rates might be higher so we need to implement a logic that will abide to the x-amzn-RateLimit-Limit response.

The only required parameter is marketplaceIds , however we need to provide some additional information in order to identify the product and this will be through the identifiers and identifierstype params.

Marketplace EAN OR Product > EAN OR Product >UPC OR Product >GTIN OR Product >ISBN | We prioritise in the same order.We pick the Product Account > Marketplace EAN with priority, then Product > EAN is second by priority and so on. Note! : It is important that we send the same identifier type with the corresponding value in it. | | identifiersType | EAN OR UPC OR GTIN OR ISBN | We need to prioritise in the same order. For example if we have EAN filled we pick this with highest priority and so on. | | includedData | <v1.1>Hardcoded as “productTypes,salesRanks”</v1.1> | We want to include this as we will need it later. |

Here again we have two possible success response scenarios. One of the responses is when the product exists in the Amazon catalogue and the other successful response is when the product does not exist on the catalogue. Let’s explore both scenarios: <v1.1> Scenario #1 (product exists) :

{
    "numberOfResults": 7,
    "items": [
        {
            "asin": "B00186ZRR6",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "11056341",
                            "title": "Bath Soaps",
                            "link": "https://www.amazon.com/gp/bestsellers/beauty/11056341",
                            "rank": 12882
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "beauty_display_on_website",
                            "title": "Beauty & Personal Care",
                            "link": "https://www.amazon.com/gp/bestsellers/beauty",
                            "rank": 924497
                        }
                    ]
                }
            ]
        },
        {
            "asin": "B001K9TMW2",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "14163029011",
                            "title": "Household Carpet Spot Cleaning Sprays",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/14163029011",
                            "rank": 58
                        },
                        {
                            "classificationId": "120225718011",
                            "title": "Sales & Deals",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/120225718011",
                            "rank": 6545
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "health_and_beauty_display_on_website",
                            "title": "Health & Household",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc",
                            "rank": 79900
                        }
                    ]
                }
            ]
        },
        {
            "asin": "B007UJ7VHY",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "14163029011",
                            "title": "Household Carpet Spot Cleaning Sprays",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/14163029011",
                            "rank": 331
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "health_and_beauty_display_on_website",
                            "title": "Health & Household",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc",
                            "rank": 801383
                        }
                    ]
                }
            ]
        },
        {
            "asin": "B00NWVRTYY",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "14163029011",
                            "title": "Household Carpet Spot Cleaning Sprays",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/14163029011",
                            "rank": 375
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "health_and_beauty_display_on_website",
                            "title": "Health & Household",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc",
                            "rank": 952009
                        }
                    ]
                }
            ]
        },
        {
            "asin": "B00QUBAXLY",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "14163029011",
                            "title": "Household Carpet Spot Cleaning Sprays",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/14163029011",
                            "rank": 328
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "health_and_beauty_display_on_website",
                            "title": "Health & Household",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc",
                            "rank": 788048
                        }
                    ]
                }
            ]
        },
        {
            "asin": "B00QUCRPO6",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "14163029011",
                            "title": "Household Carpet Spot Cleaning Sprays",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/14163029011",
                            "rank": 326
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "health_and_beauty_display_on_website",
                            "title": "Health & Household",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc",
                            "rank": 786100
                        }
                    ]
                }
            ]
        },
        {
            "asin": "B07D6WN4WF",
            "productTypes": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "productType": "CLEANING_AGENT"
                }
            ],
            "salesRanks": [
                {
                    "marketplaceId": "ATVPDKIKX0DER",
                    "classificationRanks": [
                        {
                            "classificationId": "14163029011",
                            "title": "Household Carpet Spot Cleaning Sprays",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc/14163029011",
                            "rank": 350
                        }
                    ],
                    "displayGroupRanks": [
                        {
                            "websiteDisplayGroup": "health_and_beauty_display_on_website",
                            "title": "Health & Household",
                            "link": "https://www.amazon.com/gp/bestsellers/hpc",
                            "rank": 863614
                        }
                    ]
                }
            ]
        }
    ]
}

Mapping :

</v1.1> Once we receive the response that the product exists, we need to set Product Account > Product Status > Product Created and Product Account Amazon > Catalogue Exists = Yes

Then the next step is to check the seller account is eligible to sell that item. A seller may not be eligible to sell a particular product (ASIN) in a specific Amazon marketplace. This is because there may be restrictions imposed by the brand owner. In this case, even if the product is already on the Amazon catalog, we won’t be able to push an offer. So, before submitting an offer, we need to check if the seller is eligible by making a getListingsRestrictions call.

We want the searchCatalogItems and get restrictions calls to be incorporated into one cron, we need to make only one check for the get restrictions - we want our Product Account > ChannelitemID to be empty. Just everytime we search if a product exists on the catlaogue and if it exists, we need to immediately check if we are eligible to sell it. It is up to devs to decide if we want to do it one by one or first get all asins and then check all of them for eligibility.

API Call : GET /listings/2021-08-01/restrictions Docs : https://developer-docs.amazon.com/sp-api/docs/listings-restrictions-api-v2021-08-01-reference#getlistingsrestrictions

Usage Plan:

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation but based on different sellers the rates might be higher so we need to implement a logic that will abide to the x-amzn-RateLimit-Limit response.

For this call we want to use the following params : asin, sellerId, marketplaceIds,conditionType

Mapping :

New (with tags) > new_new Manufacturer refurbished > refurbished_refurbished New other defects > new_open_box 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. |

We have two possible responses , if it is like the following one, means that we cannot list this item. We can say that because “reasons” array is not empty.

{
    "restrictions": [
        {
            "marketplaceId": "APJ6JRA9NG5V4",
            "conditionType": "new_new",
            "reasons": [
                {
                    "reasonCode": "APPROVAL_REQUIRED",
                    "message": "Per inserire i tuoi prodotti nella categoria \"Vino\" devi ottenere un'autorizzazione.",
                    "links": [
                        {
                            "resource": "https://sellercentral.amazon.it/hz/approvalrequest/restrictions/approve?asin=B0046EP7NQ",
                            "verb": "GET",
                            "title": "Request Approval via Seller Central.",
                            "type": "text/html"
                        }
                    ]
                }
            ]
        }
    ]
}

From this response we need to store the message into Product Account > Update Item Error

The second response will be a beautiful, empty, “restrictions” array and it means that we have a green light and can go over the next step!

{
    "restrictions": []
}

If there are no restrictions for this item to be sold by this seller, then we can proceed into creating the listing. In order to create a successful call and create the listing (and link it to the catalogue) we need to produce a valid json body which needs to be validated against a specific JSON schema. The JSON schema is of productType = PRODUCT (this schema is used for creating new listings against all products that are already existing on Amazon’s catalog). We will already have the json schemas for all categories saved (read Amazon SP API Taxonomy) so we just need to pick the category = PRODUCT schema and validate against it. The schema is attached below. We have the common root parameters explained in the taxonomy document.

PRODUCT.json

Few considerations on Amazon JSON Schemas

While Amazon JSON schemas are very well crafted, they are very very very complex. Remember that we are just trying to create a valid JSON document to create an offer for an existing product! Try to imagine, and you will discover what it means to create a brand new product on the catalog. It is a really complex task. But believe me: this is the best way Amazon have to provide us with the great amount of informations that we need to have in order to create a new product!

Something that might help:

• almost all of the elements normally have a marketplace_id property which have the same value all over again. It’s completely normal. I don’t know why Amazon enforces us like this, but in order to validate your document to the schema, you must do that.
• a lot of elements have a language_id property which have a different value (set in the $defs element) but repeated all over in the document, just like the marketplace_id.
• creating a valid JSON document could be a long and iterative process.

After we have successfully created a valid JSON its time that we push the offer for creation!

We have two ways of creating listings on Amazon:

1) PUT Listing Item call - We want to use this if we are pushing up to 1500 products at the same time for creation so we need to have some kind of validation

2) JSON_LISTINGS_FEED - We want to use the feeds option if we are pushing more than 1500 products for listing creation at the same time.

Put Listing Item

Using this call, we can create new or fully update a listing

All triggers, validations etc are as per the listing abstraction - Product Listing general requirements + an additional trigger which would be Product Account Amazon > Catalogue Exists = Yes

API Call: `PUT /listings/2021-08-01/items/{sellerId}/{sku}` API Docs : https://developer-docs.amazon.com/sp-api/docs/listings-items-api-v2021-08-01-reference#put-listings2021-08-01itemsselleridsku

Usage plan:

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation but based on different sellers the rates might be higher so we need to implement a logic that will abide to the x-amzn-RateLimit-Limit response.

Parameters

Mapping :

Sample call body:

{
    "productType": "PRODUCT",
    "attributes": {
        [OUR JSON DOCUMENT]
    }

}

Mapping :

A successful response will be as follows :

{
  "sku": "your sku",
  "status": "ACCEPTED",
  "submissionId": "random character string"
}

Since Amazon works with both types of validation - synchronous  and asynchronous, we need to be able to handle both. 

Once we have an ACCEPTED status this means that :

If the submission passes the synchronous validations above, the submission is accepted and is sent downstream to create or update the SKU. There are a number of downstream processes that are then performed to successfully create an item in the Amazon catalog. Any of these downstream processes can generate issues which are returned asynchronously.

So if we have successfully sent our listing for creation, however since here is another step of validation performed by Amazon in background, we need to prepare to read a notification from Amazon indicating if the listing was success or not. So we need to set Product Account > List/Update the whole item = Sent and Product Account > Listing Status = Inactive and Product Account > Product Status = Product Created.

How we handle the asyncrhonous validations will be through notifications and can be found here : Amazon SP-API Notifications

JSON_LISTINGS_FEED

API Call : JSON_LISTINGS_FEED

API Docs : https://developer-docs.amazon.com/sp-api/docs/listings-feed-type-values and https://github.com/amzn/selling-partner-api-models/tree/main/schemas/feeds

The JSON_LISTINGS_FEED feed type is contractually compatible with the Listings Items API and attributes in feed messages follow the same product type definition schemas as described in the taxonomy document. These feed submissions will enqueue our bulk submission and then invoke the Listings Items API on our behalf. When complete, the feed processing report will include any validation feedback provided by the Listings Items API.

The structure and flows are described here but the actual feed flow and response reader is available here - Amazon SP-API Orders and Products Feeds Flow

We have not managed to successfully create a valid JSON document so there are no examples. This will need to be tested as it is developed.

This completes the second case where the listing was not created but there was an existing catalogue product for this item in Amazon, however as mentioned way above (the paragraph before Scenario #1) there is a second scenario and that is when the product does not exist on Amazon’s catalogue and we need to create it.

Scenario #2 - The the product does not exist on Amazon’s catalogue (again, this is the second possible response of Search Catalog Items call) : **

{
    "numberOfResults": 0,
    "items": []
}

If there are no results in the response, this means that the product does not exist on Amazon’s catalogue and we can proceed to create it. If we get this response we want to set Product Account > Product Status = Product not created AND Product Account Amazon > Catalogue Exists = No so we can prepare the product for Catalog creation.

To create new items on Amazon catalogue we want to use the same calls and logic as the listing create :

1) PUT Listing Item call - We want to use this if we are pushing up to 1500 products at the same time for catalogue creation so we need to have some kind of validation

2) JSON_LISTINGS_FEED - We want to use the feeds option if we are pushing more than 1500 products for catalogue creation at the same time.

The only difference is that we need to validate against the relevant JSON schema for the specific product type (think of it as a category) that we are trying to create product for. So if we are creating a product in the SHOES category then we need to validate against SHOES specific JSON schema. We need to create the valid document based on the schema.

Creating Variations - The creation of Variations is only possible when we are creating a new catalogue item so this is the only point where we can create a variation and add products to it. The variation creation is happening through two attributes that are part of each JSON schema - parentage_level and child_parent_relationship.

parentage_level - We use this to specify whether a SKU is a parent or child. child_parent_relationship - The attribute indicates the Child Parent Sku Relationship of the product.

So in other words, if we have a variation we need to send a SKU with parentage_level = parent and the rest of the products in the variation with parentage_level = child and in the child_parent_relationship attribute we need to provide the relationship_type (as per the enum values) and the parent_sku. Since this will be a new logic for us, we want to use the SKU with the lowest ID of each variation for parent.
IMPORTANT! - Configuring variations with the Listings Items API is not supported for vendors at this time. So we need to have a logic and skip creating variations if we have Vendor account. More info can be found on Amazon - https://developer-docs.amazon.com/sp-api/docs/building-listings-management-workflows-guide#configuring-variation-families

All of the root attributes for us to create a valid document are explained in the taxonomy - Amazon SP API Taxonomy but the table can also be found below :

Attached you can find an example JSON schema for the Shoes category.

SHOES.json

The triggers, validations etc. are as per the listings abstraction for creating a new product on marketplace - Product Listing general requirements + additional trigger Product Account Amazon > Catalogue Exists = No

Once we have pushed the product for catalogue creation, we need to mark it and put Product Account > List/Update the whole Item > Sent. We will then have again both syncrhonous and asynchronous validation by Amazon so we need to handle both the following way :

• Synchronous - We will have this validation on the feed level. We should read the feed processing report as per this document Amazon SP-API Orders and Products Feeds Flow If there are no errors in the report, we want to keep the List/Update the whole Item > Sent so we can have the product ready for the asyncrhonous validation. If there are errors we are to act as per the abstraction Product Listing general requirements and put the product on the relevant statuses and store the error(s)
• Asynchronous - These will be handled with the notifications : Amazon SP-API Notifications . Based on the notification we need to mark the product accordingly (success or not success)