Amazon SP API Price Update v2

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)

Version	Date	Created / Updated	Notes
v1.0	13/01/2025	Hristiyan	First publish

Amazon will be deprecating certain outdated API calls, and the current stock and price call we are using is one of them. As a result, we need to update our price update call to Amazon. This document will hopefully provide a detailed explanation of the necessary changes.

Just like the stock updates, there are two possible ways for doing price updates - SKU by SKU or bulk update. Both scenarios will be addressed, with the second scenario through the JSON_LISTINGS_FEED.

We want to be able to control whether we are pushing price updates to Amazon via the Account Amazon > Update Price? flag. We want the flag to be valid for both the patch listing item and the feeds.

Patch Listing Item

Using this call we will do SKU-by-SKU price updates

All triggers, validations etc are as per abstraction - Price Update General requirements

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

API Call : PATCH /listings/2021-08-01/items/{sellerId}/{sku}?marketplaceIds={MarketplaceId}

Usage Plan:

Rate (requests per second)	Burst
5	5

The idea is to use this call whenever we have low amount of products for price update. So we want to create a logic and count how many products are pending for price update, and if the number is below the usage plan limit, we want to use this call to update. If the products are too much, we use the bulk update option. As a suggestion, we can use this if we are pushing up to 100 products at the same time for price update. Please note: as this is using the Listing Items call we need to ensure price and stock updates when below the threshold are tracking the same availability as both functions will use the same call.

Type	Name	Description	Schema	Default
Path	sellerId required	A selling partner identifier, such as a merchant account or vendor code.	string	-
Path	sku required	A selling partner provided identifier for an Amazon listing.	string	-
Query	marketplaceIds required	A comma-delimited list of Amazon marketplace identifiers for the request.	< string > array(csv)	-

Mapping :

Amazon Parameter	Hemi Field	Notes
sellerId	`Amazon Account` > `Merchant ID`
sku	`Product` > `SKU`
marketplaceIds	Hardcoded per account region

Example Call :

{
    "productType": "SHOES",
    "patches": [
      {
        "op": "replace",
        "path": "/attributes/purchasable_offer",
        "value": [
            {
                "currency": "GBP",
                "audience": "ALL",
                "discounted_price": [
                    {
                        "schedule": [
                            {
                                "end_at": "2025-12-31T10:17:24.000Z",
                                "value_with_tax": 25,
                                "start_at": "2024-12-31T06:58:11.000Z"
                            }
                        ]
                    }
                ],               
              "our_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 56.00

                    }
                  ]
                }
              ],
              "list_price":
              {
                "value_with_tax": 56.0,
                "currency": "GBP",
                "value": 56.0
            },
            "minimum_seller_allowed_price": [
                    {
                        "schedule": [
                            {
                                "value_with_tax": 23.99
                            }
                        ]
                    }
                ]
             }
          ]
          }
        ]
      }

Mapping (please note that all fields are optional so if we are missing information in any of them, we can exclude from the payload) :

Amazon Field					Hemi Field	Notes
`productType`					`Product Account` > `Primary Category ID`	This will vary based on the productType (category) we are updating

‼Please note - for the purpose of kicking of and preparing for this we are picking it with simple new fields in Product Account Amazon. We are yet to decide if we will leave final version this way or we will move it to Promotions management (in which case additional information will be added to scope). Please have this in mind when Reading and Estimating and either exclude idea of promotion from initial estimate or collectively add the additional time needed from the beginning, up to the tech team to decide. This is the same for both sync and async communication.‼

Example success response :

{
    "sku": "4064533733855",
    "status": "ACCEPTED",
    "submissionId": "25097b585ce9410bb5d1bb58d6e41445",
    "issues": []
}

Example error reseponse :

{
    "sku": "4064533733855",
    "status": "INVALID",
    "submissionId": "a5ceb0bd06884a31b60ce3d7a16420d9",
    "issues": [
        {
            "code": "4000003",
            "message": "The Amazon product type specified is invalid or not supported.",
            "severity": "ERROR",
            "categories": []
        }
    ]
}

From the success response we don’t need to map anything. If we get ACCEPTED status our update was sent successfully to Amazon. In case of any error, we want to store the issues > message in Product Account > Update Price Error and set the Product Account > Update Price = Error.

Bulk Update Using 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 follows the Patch Listing Item structure.The trigger is as per the abstraction - Price Update General requirements . The only difference is we want to use the feeds option if we are pushing more than 100 products for price update at the same time.

The feed flow and response reader is available here - Amazon SP-API Orders and Products Feeds Flow. Example call :

{
  "header": {
    "sellerId": "AXXXXXXXXXXXXX",
    "version": "2.0"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ABC123",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/purchasable_offer",
          "value": [
            {
                "currency": "GBP",
                "audience": "ALL",
                "discounted_price": [
                    {
                        "schedule": [
                            {
                                "end_at": "2025-12-31T10:17:24.000Z",
                                "value_with_tax": 25,
                                "start_at": "2024-12-31T06:58:11.000Z"
                            }
                        ]
                    }
                ],               
              "our_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 56.00

                    }
                  ]
                }
              ],
              "list_price":
              {
                "value_with_tax": 56.0,
                "currency": "GBP",
                "value": 56.0
            },
            "minimum_seller_allowed_price": [
                    {
                        "schedule": [
                            {
                                "value_with_tax": 23.99
                            }
                        ]
                    }
                ]
             }
          ]
        },        
      ]
    },
    {
      "messageId": 2,
      "sku": "ABC321",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/purchasable_offer",
          "value": [
            {
                "currency": "GBP",
                "audience": "ALL",
                "discounted_price": [
                    {
                        "schedule": [
                            {
                                "end_at": "2025-12-31T10:17:24.000Z",
                                "value_with_tax": 99,
                                "start_at": "2024-12-31T06:58:11.000Z"
                            }
                        ]
                    }
                ],               
              "our_price": [
                {
                  "schedule": [
                    {
                      "value_with_tax": 156.00

                    }
                  ]
                }
              ],
              "list_price":
              {
                "value_with_tax": 156.0,
                "currency": "GBP",
                "value": 156.0
            },
            "minimum_seller_allowed_price": [
                    {
                        "schedule": [
                            {
                                "value_with_tax": 83.99
                            }
                        ]
                    }
                ]
             }
          ]
        },        
      ]
    }
    // ... (more messages, if applicable)
  ]
}

Mapping :

Amazon Field		Hemi Field	Notes
`header`
	`sellerId`		`Amazon Account` > `Merchant ID`
	`version`		Hardcoded as 2.0
`messages`
	`messageId`		Each separate message should have unique id. We should start with 1 and each next message increments by 1
	`sku`	`Product` > `SKU`
	`operationType`		Hardcoded as “PATCH”
	`productType`	`Product Account` > `Primary Category ID`	This will vary based on the productType (category) we are updating

We should then submit the feed and wait for the response as per our Amazon SP-API Orders and Products Feeds Flow scope and update the product accordingly. Once the feed is processed, if there are any errors we store them in the Product Account > Update Price Error and raise the flag (Product Account > Update Price) accordingly to “Error”

Marketplaces / Amazon SP API - Technical Scope / Amazon SP API Product Management / Amazon SP API Price Update v2

Amazon SP API Price Update v2

Patch Listing Item

Bulk Update Using JSON_LISTINGS_FEED