Amazon External Fulfillment Inventory API Use-Case Guide

  1. What is the External Fulfilment Inventory API?

    The External Fulfilment Inventory API enables sellers to update and manage their inventory on multiple Amazon fulfilment channels such as Seller Flex/FBA Onsite, Multi Seller Flex, Easy ship and Self ship. Sellers selling across multiple channels can publish their absolute location level inventory from their own inventory management systems (POS/ERP/WMS) using this API.

  2. Terminology

    1. Absolute Inventory: The current number of units of a particular SKU available at a seller location.

    2. Sellable Inventory: The number of units of the particular SKU that is available to the Amazon customers for ordering. Sellable Inventory calculation logic:

      sellableQuantity = updateInventoryQuantity – reservedQuantity

      if (sellableQuantity < 0) then sellableQuantity=0

    3. Reserved Quantity: The number of units of the specified SKU that have been reserved for unfulfilled shipments dropped from any Amazon channel. We have implemented the concept of reserved inventory such that every time a shipment is received by Amazon, the ordered quantity of every SKU in the shipment is marked as reserved.

    4. Location: Seller controlled inventory source (warehouses, stores, manufacturing units etc.), whose inventory is being shared using the API by the seller. Every seller location is mapped at Amazon end and a unique location identifier i.e., location id is provided to the sellers. This identifier is expected to be passed while making the inventory API calls, this input is optional for Easy ship sellers operating from a single physical location.

    Note: Since Amazon maintains an inventory reservation, callers of batchInventory API must include inventory that is currently being fulfilled in any Amazon shipment as part of the overall quantity in the API's input. Once the ship label has been generated for a particular shipment, subsequent calls to the updateInventory can exclude the inventory from that particular shipment from the quantity input of the API.

  3. Tutorial 1: Publish your location level inventory to Amazon [Optional]

    This tutorial shows you how to update absolute inventory for a SKU to Amazon using update batchInventory API.

    Note: External Fulfillment Inventory APIs are optional for sellers using Seller Central to manage Easy Ship and Self Ship single location inventory.

    1. 3.1 Prerequisites

      To successfully complete this tutorial, you must have:

      1. Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.

      2. SKU Id details from the seller.

    2. 3.2 Update the inventory (batchInventory API)

      Call the batchInventory operation, passing the following query and header parameters. Maximum number for requests supported in a single batch is 10.

      Usage Plan:

      Rate (requests per second) : 50

    4. Header Parameters:

    Name Description Type Required
    x-amz-access-token The LWA access token for authorizing the request. String Yes

    Body Parameters:

    Name Description Type Required
    method POST String Yes
    uri Path for update and fetch operation, with locationId and skuId as query parameters.
    • Update Path: "/inventory/update?locationId=DEFAULT&skuId=efptestsku1"
    • Fetch Path: "/inventory/fetch?locationId=DEFAULT&skuId=efptestsku2"

    Note: LocationId value for Easy Ship and Self Ship single location will be "DEFAULT". For Seller Flex this value will be 4- character site code e.g., XNRF

    		String Yes
    quantity The absolute number of items of the specified SKU available at the specified location. This value should always be a non-zero positive integer. Not required for Fetch operation. Integer Yes, only for update operation
    clientSequenceNumber A unique number provided with each call to update the inventory. This number must always be a unique and increasing value per SKU per location for each inventory update. This is used by Amazon to ensure the correct sequence of updates, especially if Amazon receives near-concurrent inventory updates for the same SKU and same location. This has to be an integer, and not a floating-point number. Recommended: Date time in EPOCH format. Not required for Fetch operation. Long (int64) Yes, only for update operation
    marketplaceAttributes It contains "channelName" and "marketplaceId", this is required only when multiple channels are having same locationId. object
    (MarketplaceAttributes)    		 No

    Request Example: 

    curl -X POST "https://sellingpartnerapi-na.amazon.com/externalFulfillment/inventory/2024-09-11/inventories"

    Request Body (Maximum 10 SKUs): 

    {
    "requests": [
        {
            "method": "POST",
            "uri": "/inventory/update?locationId=DEFAULT&skuId=efptestsku1",
            "body": {
                "quantity": 25,
                "clientSequenceNumber": 12345678,
                "marketplaceAttributes": {
                    "marketplaceId": "AXJDDKDFDKDF",
                    "channelName": "MFN"
                }
            }
        }
    ]
}

    Response Example: A successful response includes the following objects: 

    {
    "responses": [
        {
            "status": {
                "statusCode": 200,
                "reasonPhrase": "Success"
            },
            "body": {
                "locationId": "DEFAULT",
                "sellableQuantity": 20,
                "reservedQuantity": 5,
                "clientSequenceNumber": 12345678,
                "marketplaceAttributes": {
                    "marketplaceId": "AXJDDKDFDKDF",
                    "channelName": "MFN"
                },
                "skuId": "efptestsku1",
                "actionableErrors": []
            }
        }
    ]
}

  4. Tutorial 2: Retrieve your location level inventory from Amazon

    This tutorial shows you how to retrieve absolute inventory for a SKU belonging to a specific seller location from Amazon.

    1. 4.1 Prerequisites

      To successfully complete this tutorial, you must have:

      1. Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.

      2. The location id and SKU id details from the seller.

    2. 4.2 Fetch the inventory (batchInventory API)

      Call the batchInventory API operation, passing the following parameters. Maximum number for requests supported in a single batch is 10.

      Usage Plan:

      Rate (requests per second) : 50

    5. Header Parameters:

    Name Description Type Required
    x-amz-access-token The LWA access token for authorizing the request. String Yes

    Body Parameters:

    Name Description Type Required
    method POST String Yes
    uri Path for update and fetch operation, with locationId and skuId as query parameters.
    • Update Path: "/inventory/update?locationId=DEFAULT&skuId=efptestsku1"
    • Fetch Path: "/inventory/fetch?locationId=DEFAULT&skuId=efptestsku2"

    Note: LocationId value for Easy Ship and Self Ship single location will be "DEFAULT". For Seller Flex this value will be 4- character site code e.g., XNRF

    		String Yes
    marketplaceAttributes It contains "channelName" and "marketplaceId", this is required only when multiple channels are having same locationId. object
    (MarketplaceAttributes)    		 No

    Request Example: 

    curl -X POST "https://sellingpartnerapi-na.amazon.com/externalFulfillment/inventory/2024-09-11/inventories"

    Request Body (Maximum 10 SKUs): 

    {
    "requests": [
        {
            "method": "POST",
            "uri": "/inventory/fetch?locationId=DEFAULT&skuId=efptestsku1",
            "body": {
                "marketplaceAttributes": {
                    "marketplaceId": "AXJDDKDFDKDF",
                    "channelName": "MFN"
                }
            }
        }
    ]
}

    Response Example: A successful response includes the following objects: 

    {
    "responses": [
        {
            "status": {
                "statusCode": 200,
                "reasonPhrase": "Success"
            },
            "body": {
                "locationId": "DEFAULT",
                "sellableQuantity": 20,
                "reservedQuantity": 5,
                "clientSequenceNumber": 12345678,
                "marketplaceAttributes": {
                    "marketplaceId": "AXJDDKDFDKDF",
                    "channelName": "MFN"
                },
                "skuId": "efptestsku1",
                "actionableErrors": []
            }
        }
    ]
}

  5. Best Practices

    For day-to-day operations, only push inventory for those SKUs (using batchInventory API) where there is a change in inventory position rather than syncing the inventory of the entire catalog in a periodic frequency.