Catalog Upload

What's New: Multiple External Product IDs
Upload Catalog
- Upload Limits
Body parameter
Example responses
Response payload examples

As your company uses Amazon’s retail technology, you will need to provide Amazon with a catalog of detailed product information for the products you sell and keep this information up-to-date. You can update your catalog manually using the 3PCC Portal or you can use our Catalog API, which allows you to programmatically update your catalog through a simple REST API. This spec will assist you in automating your catalog updates using the Amazon Catalog API.

Note: In the future, new attributes might be added. We recommend that you structure your code so that it can handle new attributes gracefully

What's New: Multiple External Product IDs

You can now associate multiple external product identifiers (barcodes, UPCs, PLUs, etc.) to a single item SKU using the additional_external_product_information field. This enhancement supports:

Multiple barcodes per product: Associate up to 50 additional external product IDs to one item SKU
Enhanced product flexibility: Support products that have multiple barcodes

Upload Catalog

POST /v1/catalog/upload

This method is used for JWO stores. The UploadCatalog API method allows you to upload list of items available for sale in your JWO store to the Amazon systems

Upload Limits

Maximum items per upload: 10,000 catalog items
If you need to upload more than 10,000 items, split your catalog into multiple API calls

Body parameter

{
  "catalogItems": [
    {
      "item_sku": "string",
      "external_product_id": "string",
      "external_product_id_type": "string",
      "additional_external_product_information": [
        {
          "external_product_id": "string",
          "external_product_id_type": "string"
        }
      ],
      "item_name": "string",
      "store_id": "string",
      "standard_price": "string",
      "brand_name": "string",
      "product_tax_code": "string",
      "product_category": "string",
      "product_subcategory": "string"
    }
  ]
}

Data Field	Required	Description
item_sku	Required	<= 255 characters. A unique identifier for the product, assigned by the retailer. The SKU must be unique for each product listed.
external_product_id	Required	<= 255 characters. A standard, alphanumeric string that uniquely identifies the product and should match the barcode value that will be scanned as part of inventory stocking. Scannable barcodes can either be 12/8 digits (UPC), 13 digits (EAN), 8 digits (EAN8), 10 digits (ISBN), 14 digits (GTIN) or PLU (Integer).
external_product_id_type	Optional	<= 255 characters. The type of standard, unique identifier entered in the scannable barcode field. For example it can be UPC, ISBN, EAN, EAN8, GTIN or PLU
additional_external_product_information	Optional	Array of additional external product identifiers. Maximum 50 items. Each item contains external_product_id (Required) and external_product_id_type (Optional) fields with the same format as the primary external product fields.
item_name	Required	<= 255 characters. A short title for a product.
store_id	Required	<= 255 characters. The store_id field contains a unique identifier for your store defined during your onboarding process with Amazon. The storeId is also used when uploading the store catalog into the JWO portal
standard_price	Optional	<= 10 characters. This price can either include price without tax or price with tax at which an item is being sold in the local currency.
brand_name	Optional	<= 255 characters The brand name of the product.
product_tax_code	Optional	<= 255 characters. Amazon Standard code to identify the tax properties of a product.
product_category	Optional	<= 50 characters. This is a custom field you can use to categorize your products and enable grouping and filtering in analytics dashboards and reports.
product_subcategory	Optional	<= 50 characters.This is a custom field you can use to categorize your products and enable grouping and filtering in analytics dashboards and reports.

Example responses

Status	Meaning	Description
201	OK	Unique ID for a catalog upload to Amazon systems. Amazon will generate a unique id for each catalog upload
400	Bad Request	You will respond with a 400 error message when the API call fails due to a validation error.
429	Too Many Requests	You will respond with a 429 error message when the API is called too many times. When you receive a 429 error due to multiple calls to the API you will receive the following response. errorMsg: Too Many Requests
500	Internal Server Error	You will respond with a 500 error message when the API call fails due to an error.

Response payload examples

Status code	Message	Meaning
201	`{ "ingestionId": "96893e97-8da8-4858-a79d-a31ffb003871" }`	If your request to Amazon's Catalog Upload API is successful, you will receive a 201 HTTP Status Code and a JSON object containing the ingestionId.
400	`{ "errorMsg": "One or more StoreID's present in the request is incorrect" }`	If API is invoked with ALL invalid storeId value
400	`{ "errorMsg": "List of store ID's present in the request are either incorrect/not associated with same retailer" }`	If API is invoked with storeId's associated with different retailers
400	`{ "errorMsg": "List of store ID's present in the request are either incorrect/not associated with same retailer" }`	If API is invoked with a mixture of invalid and correct storeId's
400	`{ "message": "Invalid request body" }`	If API is invoked with invalid request model parameters or upload catalog list has length greater than threshold
500	`{ "errorMsg": "Exception encountered while processing the request, please retry again." }`	If API call encountered an unknown error and we recommend you retry
500	`{ "errorMsg": "Exception encountered while processing the request" }`	If API call encountered an unknown error and retry is NOT recommended
429	`{ "message": "Too Many Requests" }`	If API call encountered too many requests