Amazon SP API Stock 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)

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 stock update call to Amazon. This document will hopefully provide a detailed explanation of the necessary changes.

When discussing stock updates to Amazon, we need to consider two scenarios: SKU-by-SKU updates and bulk updates. 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 stock updates to Amazon via the Account Amazon > Update Stock? 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 quantity updates.

All triggers, validations etc are as per abstraction - Stock 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:

The idea is to use this call whenever we have low amount of products for quantity update. So we want to create a logic and count how many products are pending for quantity 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 quantity update. Please note: as this is using the Listing Items call we need to ensure stock and price updates when below the threshold are tracking the same availability as both functions will use the same call.

Mapping :

Example Call :

{
  "productType": "SHOES",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "DEFAULT",
          "quantity": 100
        }
      ]
    }
  ]
}

Mapping :

If this is missing we should treat this as an error and set the message to “Missing Amazon Category” | | patches | | | | | | | op | | | Hardcoded as “replace” | | | path | | | Hardcoded as "/attributes/fulfillment_availability" | | | value | | | | | | | fulfillment_channel_code | | Hardcoded as “DEFAULT” | | | | quantity | Product Account > Quantity | |

Example success response :

{
    "sku": "4064533733473",
    "status": "ACCEPTED",
    "submissionId": "528b2cf1c86a4a709b86ce04baf2455f",
    "issues": []
}

Example error response :

{
    "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 response we don’t need to map anything. As long as we get ACCEPTED response this means that our update was sent successfully to Amazon. In case of any error, we want to store the issues > message in Product Account > Error Updating Quantity and set the Product Account > Update Quantity = 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 -Stock Update general requirements. The only difference is we want to use the feeds option if we are pushing more than 100 products for quantity 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": "SHOES",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT",
              "quantity": 5
            }
          ]
        }        
      ]
    },
    {
      "messageId": 2,
      "sku": "ABC321",
      "operationType": "PATCH",
      "productType": "SHOES",
      "patches": [
        {
          "op": "replace",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT",
              "quantity": 10
            }
          ]
        }        
      ]
    },
    //... (more messages)
  ]
}

Mapping :

If this is missing we should treat this as an error and set the message to “Missing Amazon Category” | | | patches | | | | | | | | op | | | Hardcoded as “replace” | | | | path | | | Hardcoded as “/attributes/fulfillment_availability” | | | | value | | | | | | | | fulfillment_channel_code | | Hardcoded as “DEFAULT” | | | | | quantity | Product Account > Quantity | |

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 > Error Updating Quantity and raise the flag (Product Account > Update Quantity) accordingly to “Error”