Multi-Location Inventory Integration Guide
Integrate MLI with APIs and operations to provide location-level data for customers.
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:
- Create new or update existing supply sources through the Supply Sources API or the Seller Central UI.
- Provide location-specific inventory via the API.
- Create or identify existing templates allowed by Shipping Settings Automation (SSA) that include all of your inventory locations that use these shipping settings.
- Assign the shipping template created or identified in Step 3 to the SKUs you added inventory per location.
- Set the
DEFAULT
inventory channel to0
. - 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:
API reference | API version | Use case guide |
---|---|---|
Supply Sources API | 2020-07-01 | Supply Sources API Use Case Guide |
Listings Items API | 2021-08-01 | Listings Items API Use Case Guide |
Feeds API | 2021-06-30 | Feeds API Use Case Guide |
Create MLI shipping templates allowed by Shipping Settings Automation (SSA) in Seller Central
- Log in to your Seller Central account.
- Hover over the Settings Icon (Gear) in the top-right corner and choose Shipping Settings.
- Under the Shipping Templates navigation tab, select Create New Shipping Template.
- In the overlay window, select Create to start a new shipping template.
- Select all the supply sources that will be used for MLI.
- Select your preferred fulfillment type and choose Next.
- Select your preferred shipping services and regional preferences and choose Next.
- Select your preferred premium shipping automation and choose Next.
- Review your selections, then choose Confirm.
- Name and configure your new template.
- 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 to0
You must set the
DEFAULT
channel to0
. Failure to set theDEFAULT
channel to0
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
Parameter | Description | Required |
---|---|---|
sellerId |
The Selling Partner identifier, such as the Merchant Customer Identifier (MCID) or the Vendor code. | Yes |
sku |
The SKU identifier of the listing that is unique to the seller ID. | Yes |
marketplaceIds |
The comma-delimited list of marketplace identifiers for the request. | Yes |
issueLocale |
The locale for the issue localization. When not provided, the default language code of the first marketplace is used. Examples: en_US, fr_CA, fr_FR. Localized messages default to en_US when a localization is not available in the specified language. | No |
Header parameters
Name | Value |
---|---|
Accepts |
application/json |
Content-Type |
application/json |
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
Name | Description | Required |
---|---|---|
sellerId |
The Selling Partner identifier, such as the Merchant Customer Identifier (MCID) or the Vendor code. | Yes |
sku |
The SKU identifier for the listing that is unique to the sellerId. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
marketplaceIds |
The comma-delimited list of marketplace identifiers for the request. | Yes |
issueLocale |
The locale for issue localization. When not provided, the default language code of the first marketplace is used. Examples: en_US, fr_CA, fr_FR. Localized messages default to en_US when a localization is not available in the specified language. | Optional |
includedData |
The comma-delimited list of marketplace identifiers for the request. Type: array(csv) |
No |
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
-
GET
the listing call to find the quantity of an individual SKU for the default location. This example uses thessnm001
SKU, which has a quantity of three at a single supply source.*Example request
GET: {{baseUrl}}/listings/2021-08-01/items/{{sellerid}}/ssnm001?marketplacelds={{Marketplaceld}}
Example response
{ "sku": "ssnm001", "fulfillmentAvailability": [ { "fulfillmentChannelCode": "DEFAULT", "quantity": 3 } ] }
-
Use the
PATCH
operation and set thefulfillmentChannelCode
toDEFAULT
and thequantity
to0
.Example request
PATCH: {{baseUrl}}/listings/2021-08-01/items/{{sellerid}}/ssnm001?marketplacelds={{Marketplaceld}}
{ "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
{ "sku": "ssnm001", "status": "ACCEPTED", "submissionId": "680b16163093417da2edfd77a7edc38f", "issues": [] }
-
Use the
GET
operation to submit the changes and retrieve details about thefulfillmentAvailability
to the SKU set in the previous step and check that the changes were applied.Example request
GET: {{baseUrl}}/listings/2021-08-01/items/{{sellerId}}/ssnm001?marketplacelds={{Marketplaceld}}&includedData=fulfillmentAvailability
Example response
{ "sku": "ssnm001", "fulfilmentAvailability": [ { "fulfillmentchannelCode": "DEFAULT", "quantity": 9 }, { "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3", "quantity": 10 }, { "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0", "quantity": 5 } ] }
-
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:- Log in to your Seller Central account.
- In the top-left corner, select the hamburger menu and expand it.
- Hover over Inventory and select Manage All Inventory.
- 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
andCarrierName
valuesWhen 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 theCarrierName
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.
Once 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
-
Create a feed document with two SKUs and assign both to two supply sources. This example uses the
ssnm001
andssnm002
SKUs.Example Request
POST: {{baseUrl}}/feeds/2021-06-30/documents
{ "contentType": "application/json; charset=UTF-8" }
Example response
{ "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" }
-
Upload a single JSON for all SKUs and adjust the inventory level of each supply source.
Example request
POST: {{FeedUrl}}
{ "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
-
Create a feed.
Example request
POST: {{baseUrl}}/feeds/2021-06-30/feeds
var jsonData=JSON.parse(responseBody); postman.setEnvironmentVariable("feedId", jsonData. feedId);
Example response
{ "feedId": "50037019429" }
-
GET
the feed document.Example request
GET: {{baseUrl}}/feeds/2021-06-30/feeds/:feedId
Example response
{ "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" }
-
Verify quantities for both SKUs.
Example request
GET: {{baseUrl}}/listings/2021-08-01/items/{{sellerId}}/ssnm001?marketplacelds={{Marketplaceld}}&includedData=fulfillmentAvailability
GET: {{baseUrl}}/listings/2021-08-01/items/{{sellerId}}/ssnm002?marketplacelds={{Marketplaceld}}&includedData=fulfillmentAvailability
Example response
{ "sku": "ssnm001", "fulfillmentAvailability": [ { "fulfillmentchannelCode": "DEFAULT", "quantity": 15 }, { "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3", "quantity": 10 }, { "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0", "quantity": 5 } ] }
{ "sku": "ssnm002", "fulfillmentAvailability": [ { "fulfillmentchannelCode": "DEFAULT", "quantity": 17 }, { "fulfillmentchannelCode": "353e4e48-6301-4d50-990e-43a86e8787a3", "quantity": 10 }, { "fulfillmentchannelCode": "8e07a0c9-ab0a-4108-9f16-83dc3496bee0", "quantity": 7 } ] }
-
Verify that the inventory quantity has also been updated in Seller Central using the following steps:
- Log in to your Seller Central account.
- In the top-left corner, select the hamburger menu and expand it.
- Hover over Inventory and select Manage All Inventory.
- Check the SKU number the supply sources.
Troubleshooting
If you receive authorization errors, refer to Authorization Errors.
Updated 23 days ago