Multi-Location Inventory Integration Guide

Multi-Location Inventory (MLI) allows multi-location sellers to provide Amazon with location-level data on their inventory and actual fulfillment capabilities. This location-level data, paired with the Seller’s ship-from location data, generates precise information for customers to review. MLI increases sellers' speed and reliability and lowers the cost to serve, making offers more attractive to customers, driving MFN sales, and increasing seller profits. This guide advises Selling Partners on the APIs and operations that are mandatory to successfully integrate MLI.

🚧

MLI is currently not available for the following sellers:

• Sellers who use FBA inventory.
• Sellers who manage their inventory via Seller Central.

Prerequisites

Your seller account must have the required permissions to use MLI. If your account does not have MLI permissions, you can request access through the Multi-Location Inventory Sign-up Form. You will receive confirmation that your account is ready within 15 business days.

After your account has the required permissions to use MLI, your default location and any locations you created on templates allowed by Shipping Settings Automation (SSA) will be automatically added as supply sources.

Finish setting up your seller account through the following steps:

1. Create new or update existing supply sources through the Supply Sources API or the Seller Central UI.
2. Provide location-specific inventory via the API.
3. Create or identify existing templates allowed by Shipping Settings Automation (SSA) that include all of your inventory locations that use these shipping settings.
4. Assign the shipping template created or identified in Step 3 to the SKUs you added inventory per location.
5. Set the DEFAULT inventory channel to 0.
6. Add the Selling Partner Insights role to your developer profile.

Mandatory APIs for MLI integration

Selling Partners should integrate the Supply Sources API, the Listings Items API, and the Feeds API to leverage MLI. For more detailed information about the individual API operations listed, refer to the following table:

Create MLI shipping templates allowed by Shipping Settings Automation (SSA) in Seller Central

1. Log in to your Seller Central account.
2. Hover over the Settings Icon (Gear) in the top-right corner and choose Shipping Settings.
3. Under the Shipping Templates navigation tab, select Create New Shipping Template.
4. In the overlay window, select Create to start a new shipping template.
5. Select all the supply sources that will be used for MLI.
6. Select your preferred fulfillment type and choose Next.
7. Select your preferred shipping services and regional preferences and choose Next.
8. Select your preferred premium shipping automation and choose Next.
9. Review your selections, then choose Confirm.
10. Name and configure your new template.
11. Choose Save.

Integrate the Supply Sources API

To learn how to use MLI program with the Supply Sources API, refer to the Supply Sources API Use Case Guide.

Integrate the Listings Items API

The Listings Items API allows sellers to replace inventory count available at a supply source. The Listings Items API accepts PATCH operations to update and delete one or more individual attributes for an existing listing, such as price and quantity.

🚧

Set the DEFAULT channel to 0

You must set the DEFAULT channel to 0. Failure to set the DEFAULT channel to 0 will result in multiple offers being listed: one MLI offer, and one non-MLI offer. This will not affect the buy-ability of the offer, but can result in less accurate promises being made by the non-MLI offer.

Use MLI to update your inventory

Use the PATCH operation with the endpoint /listings/2021-08-01/items/{sellerId}/{sku}?marketplaceIds={marketplaceIds}&issueLocale={issueLocale}, then pass the following parameters:

Path parameters

Header parameters

Example request for an SKU with a single fulfillment channel

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "replace",
            "path": "/attributes/fulfillment_availability",
            "value": [
                {
                    "fulfillment_channel_code": "StoreID1234567",
                    "quantity": 10
                }
            ]
        }
    ]
}

Example response for an SKU with a single fulfillment channel

🚧

Always set the following fields to the corresponding values:

• Product Type = PRODUCT
• Path = /attributes/fulfillment/availability

{
    "sku": "SKUID1234567",
    "status": "ACCEPTED",
    "submissionId": "f1dc2914-75dd-11ea-bc55-0242ac130003",
    "issues": []
}

Example request for an SKU with multiple fulfillment channels

{
    "productType": "PRODUCT",
    "patches": [
        {
            "op": "replace",
            "path": "/attributes/fulfillment_availability",
            "value": [
                {
                    "fulfillment_channel_code": "ISPU01",
                    "quantity": 10
                },
                {
                    "fulfillment_channel_code": "ISPU02",
                    "quantity": 10
                }
            ]
        }
    ]
}

Example response for an SKU with multiple fulfillment channels

{
    "header": {
        "sellerId": "{merchantId}",
        "version": "2.0",
        "issueLocale": "en_US"
    },
    "messages": [
        {
            "messageId": 1,
            "sku": "My-SKU-01",
            "operationType": "PATCH",
            "productType": "PRODUCT",
            "patches": [
                {
                    "op": "replace",
                    "path": "/attributes/fulfillment_availability",
                    "value": [
                        {
                            "fulfillment_channel_code": "ISPU01",
                            "quantity": 10
                        },
                        {
                            "fulfillment_channel_code": "ISPU02",
                            "quantity": 10
                        }
                    ]
                }
            ]
        },
        {
            "messageId": 2,
            "sku": "My-SKU-02",
            "operationType": "PATCH",
            "productType": "PRODUCT",
            "patches": [
                {
                    "op": "replace",
                    "path": "/attributes/fulfillment_availability",
                    "value": [
                        {
                            "fulfillment_channel_code": "ISPU01",
                            "quantity": 10
                        },
                        {
                            "fulfillment_channel_code": "ISPU02",
                            "quantity": 10
                        }
                    ]
                }
            ]
        }
    ]
}

Use MLI to view your inventory

The Listings Items API allows sellers to view inventory count available at the supply source. Call the getListingsItem operation to return details about a listings items.

Use the GET operation with the endpoint /listings/2021-08-01/items/{sellerId}/{sku}?marketplaceIds={marketplaceIds}&issueLocale={issueLocale} &includedData=issues,attributes,summaries,offers,fulfillmentAvailability and pass the following parameters:

Path parameters

Query parameters

A successful response incudes the Fulfillment Availability array attribute that returns the Supply Source ID (fulfillmentChannelCode) and the remaining inventory count (quantity).For request and response examples, refer to the Listings Items API Use Case Guide.

Assign inventory for individual SKUs

1. GET the listing call to find the quantity of an individual SKU for the default location. This example uses the ssnm001 SKU, which has a quantity of three at a single supply source.

   *Example request

   HTTP

   GET: {{baseUrl}}/listings/2021-08-01/items/{{sellerid}}/ssnm001?marketplacelds={{Marketplaceld}}
   

   Example response

   JSON

   {
       "sku": "ssnm001",
       "fulfillmentAvailability": [
           {
               "fulfillmentChannelCode": "DEFAULT",
                   "quantity": 3
           }
       ]
   }
   

2. Use the PATCH operation and set the fulfillmentChannelCode to DEFAULT and the quantity to 0.

   Example request

   HTTP

   PATCH: {{baseUrl}}/listings/2021-08-01/items/{{sellerid}}/ssnm001?marketplacelds={{Marketplaceld}}
   

   JSON

   {
   "productType": "PRODUCT",
           "Patches": [
           {
               "op": "replace",
               "path": "/attributes/fulfillment_availability",
               "value": [
                   {
                       "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3",
                       "quantity": 10
                   },
                   {
                       "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0",
                       "quantity": 5
                   },
                   {
   
                       "fulfillmentchannelCode": "DEFAULT",
                       "quantity": 0
                   }
               ]
           }
       ]
   }
   

   Example response

   JSON

   {
       "sku": "ssnm001",
           "status": "ACCEPTED",
       "submissionId": "680b16163093417da2edfd77a7edc38f",
           "issues": []
   }
   

3. Use the GET operation to submit the changes and retrieve details about the fulfillmentAvailability to the SKU set in the previous step and check that the changes were applied.

   Example request

   HTTP

   GET: 
   {{baseUrl}}/listings/2021-08-01/items/{{sellerId}}/ssnm001?marketplacelds={{Marketplaceld}}&includedData=fulfillmentAvailability
   

   Example response

   JSON

   {
       "sku": "ssnm001",
           "fulfilmentAvailability": [
           {
               "fulfillmentchannelCode": "DEFAULT",
               "quantity": 9
           },
   {
               "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3",
               "quantity": 10
           },
   {
               "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0",
               "quantity": 5
           }
   
       ]
   }
   

4. It is confirmed that the SKU is ssnm001 and the inventory will be consolidated from two supply sources with the aliases SS Store - Milipitas and Cuentazilla. Verify that the quantity has also been updated in Seller Central using the following steps:

   1. Log in to your Seller Central account.
   2. In the top-left corner, select the hamburger menu and expand it.
   3. Hover over Inventory and select Manage All Inventory.
   4. Check the SKU number the supply sources.

Integrate the Feeds API

Retrieve the supply source ID used by Selling Partners through the Order fulfillment feed

At this time, Amazon does not support ShipFromSupplySourceId and Sellers should use the ShipFromAddress XML Schema instead.

For more information, review POST_ORDER_FULFILLMENT_DATA in the Order feeds attributes. 

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

    <xsd:include schemaLocation="amzn-base.xsd"/>

    <xsd:element name="OrderFulfillment">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:choice>
                    <xsd:element ref="AmazonOrderID"/>
                    <xsd:element ref="MerchantOrderID"/>
                </xsd:choice>
                <xsd:element name="MerchantFulfillmentID" type="IDNumber" minOccurs="0"/>
                <xsd:element name="FulfillmentDate" type="xsd:dateTime"/>
                <xsd:element name="FulfillmentData" minOccurs="0">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:element ref="CarrierCode" minOccurs="0"/>
                            <xsd:element name="CarrierName" type="String" minOccurs="0"/>
                            <xsd:element name="ShippingMethod" type="String" minOccurs="0"/>
                            <xsd:element name="ShipperTrackingNumber" type="String" minOccurs="0"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>

                <xsd:element name="CODCollectionMethod" minOccurs="0">
                    <xsd:simpleType>
                        <xsd:restriction base="xsd:string">
                            <xsd:enumeration value="DirectPayment"/>
                        </xsd:restriction>
                    </xsd:simpleType>
                </xsd:element>

                <xsd:element name="Item" minOccurs="0" maxOccurs="unbounded">
                    <xsd:complexType>
                        <xsd:sequence>
                            <xsd:choice>
                                <xsd:element ref="AmazonOrderItemCode"/>
                                <xsd:element ref="MerchantOrderItemID"/>
                            </xsd:choice>
                            <xsd:element name="MerchantFulfillmentItemID" type="IDNumber"
                                minOccurs="0"/>
                            <xsd:element name="Quantity" type="xsd:positiveInteger" minOccurs="0"/>
                             <xsd:element name="TransparencyCode" type="xsd:string" minOccurs="0" maxOccurs="10"/>
                        </xsd:sequence>
                    </xsd:complexType>
                </xsd:element>
                <xsd:element name="ShipFromAddress" type="AddressType" minOccurs="0" />

            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>

</xsd:schema>

Confirm multiple orders through the Order Fulfillment feed

To confirm an order or a group of orders using the POST_ORDER_FULFILLMENT_DATA feed type, you must include CarrierCode, ShippingMethod, and ShipperTrackingNumber within the XML schema. You can also integrate the POST_ORDER_FULFILLMENT_DATA feed type to confirm merchant-fulfilled orders.

XML example

<?xml version="1.0" encoding="utf-8"?>
<AmazonEnvelope
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Header>
        <DocumentVersion>1.01</DocumentVersion>
        <MerchantIdentifier>MerchantID</MerchantIdentifier>
    </Header>
    <MessageType>OrderFulfillment</MessageType>
    <Message>
        <MessageID>1</MessageID>
        <OrderFulfillment>
            <AmazonOrderID>7XX-XXXXXXX-XXXXXXX</AmazonOrderID>
            <FulfillmentDate>2023-01-01T01:01:01+00:00</FulfillmentDate>
            <FulfillmentData>
                <CarrierCode>USPS</CarrierCode>
                <ShippingMethod>USPS First Class Mail</ShippingMethod>
                <ShipperTrackingNumber>1234567891011121314</ShipperTrackingNumber>
            </FulfillmentData>
        </OrderFulfillment>
    </Message>
</AmazonEnvelope>

New carriers are regularly being added to the Seller Central UI. If the CarrierCode value of the carrier you wish to use is not mapped into the amzn-base XSD file, use the CarrierCode value of Other and provide the carrier name in the CarrierName field. When you use this method, Amazon will not be able to track package shipping updates.

📘

Include CarrierCode and CarrierName values

When using an unlisted carrier to fulfill orders on Amazon, you must use the CarrierCode attribute with the value of Other and provide the carrier name in the CarrierName field to confirm shipments. Sellers who do not provide this information may experience an increase in their late shipment rate and automatically canceled orders due to unconfirmed shipments.

After you've created the XML with the necessary information, you can use the POST_ORDER_FULFILLMENT_DATA feed type to prompt Amazon to notify the buyer that the order is on its way.

Make bulk updates

The Feeds API can also make bulk updates. To refer to an example feed with two SKUs, each containing multiple fulfillment updates, refer to the Listings Feeds API.

Assign inventory for multiple SKUs

1. Create a feed document with two SKUs and assign both to two supply sources. This example uses the ssnm001 and ssnm002 SKUs.

   Example Request

   HTTP

   POST: {{baseUrl}}/feeds/2021-06-30/documents
   

   JSON

   {
   "contentType": "application/json; charset=UTF-8"
   }
   

   Example response

   JSON

   {
       "feedDocumentId": "amzn1.tortuga.4.na.116e0ef0-ae4e-4430-9c13-249cd489c9a.T20RL98XXLBHV9",
           "url": "https://tortuga-prod-na.s3-external-1.amazonaws.com/&2FNinetyDays/amzn1.tortuga.4.na.116e0ef0-ae4e-4430-9c13-249cd48f9c9a.T20RL98XXLBHV9?X"
   }
   

2. Upload a single JSON for all SKUs and adjust the inventory level of each supply source.

   Example request

   HTTP

   POST: {{FeedUrl}}
   

   JSON

   {
   "header":{
       "sellerId": "A1PP0FEH11RW77",
       "version": "2.0",
   },
   "messages":[
       {
           "messageId": 1,
           "sku": "ssnm002",
           "operationType": "PATCH",
           "patches": "PRODUCT",
               {
                   "op": "replace"
                   "path": "/attributes/fulfillment_availability"
                   "value": [
                   {
                               "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3",
                               "quantity": 10
                           },
   {
                               "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0",
                               "quantity": 7
                           },		
   {
                               "fulfillmentchannelCode": "DEFAULT",
                               "quantity": 0
                           }
                       ]
                   }
               ]
           },
           {
           "messageId": 2,
           "sku": "ssnm001",
           "operationType": "PATCH",
           "patches": "PRODUCT",
               {
                   "op": "replace"
                   "path": "/attributes/fulfillment_availability"
                   "value": [
                   {
                               "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3",
                               "quantity": 5
                           },
   {
                               "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0",
                               "quantity": 8
                           },		
   {
                               "fulfillmentchannelCode": "DEFAULT",
                               "quantity": 0
                           }
                       ]
                   }
               ]
           },
       ]
   }
   
   }
   

   Example response

3. Create a feed.

   Example request

   HTTP

   POST: {{baseUrl}}/feeds/2021-06-30/feeds
   

   HTTP

   var jsonData=JSON.parse(responseBody);
   postman.setEnvironmentVariable("feedId", jsonData. feedId);
   

   Example response

   JSON

   {
       "feedId": "50037019429"
   }
   

4. GET the feed document.

   Example request

   HTTP

   GET: {{baseUrl}}/feeds/2021-06-30/feeds/:feedId
   

   Example response

   JSON

   {
       "createdTime": "2023-03-12T21:23:02+00:00",
       "processingStatus": "DONE ",
       "marketplaceIds": [
   "ATVPDKIKX0DER",
       ],
       "feedId": "50037019429",
       "feedType": "JSON_LISTINGS_FEED",
       "createdTime": "2023-03-12T21:23:02+00:00",
       "processingStartTime": "2023-03-12T21:23:02+00:00",
       "resultFeedDocumentId": "amzn1.tortuga.4.na.55£45d82-9068-4386-bbdd-9d0b7330c2e1.T3HAQ94M1R94U6"
   }
   

5. Verify quantities for both SKUs.

   Example request

   HTTP

   GET: 
   {{baseUrl}}/listings/2021-08-01/items/{{sellerId}}/ssnm001?marketplacelds={{Marketplaceld}}&includedData=fulfillmentAvailability
   

   HTTP

   GET: {{baseUrl}}/listings/2021-08-01/items/{{sellerId}}/ssnm002?marketplacelds={{Marketplaceld}}&includedData=fulfillmentAvailability
   

   Example response

   JSON

   {
       "sku": "ssnm001",
           "fulfillmentAvailability": [
           {
               "fulfillmentchannelCode": "DEFAULT",
               "quantity": 15
           },
   {
               "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3",
               "quantity": 10
           },
   {
               "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0",
               "quantity": 5
           }
   
   
       ]
   }
   

   JSON

   {
       "sku": "ssnm002",
           "fulfillmentAvailability": [
           {
               "fulfillmentchannelCode": "DEFAULT",
               "quantity": 17
           },
   {
               "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3",
               "quantity": 10
           },
   {
               "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0",
               "quantity": 7
           }
   
       ]
   }
   

6. Verify that the inventory quantity has also been updated in Seller Central using the following steps:

   1. Log in to your Seller Central account.
   2. In the top-left corner, select the hamburger menu and expand it.
   3. Hover over Inventory and select Manage All Inventory.
   4. Check the SKU number the supply sources.

Troubleshooting

If you receive authorization errors, refer to Authorization Errors.