Multi-Location Inventory Integration Guide

Integrate multi-location inventory with APIs and operations to provide location-level data for customers.

Sellers can use multi-location inventory to provide Amazon with location-level data for their data and fulfillment capabilities. This location-level data, paired with the seller’s ship-from location data, generates precise information for customers to review. Multi-location inventory 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 multi-location inventory.

🚧
Multi-location inventory is currently not available for sellers who:

Use FBA inventory

Manage their inventory with Seller Central

Prerequisites

Your seller account must have the required permissions to use multi-location inventory. If your account does not have multi-location inventory 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 you obtain the required permissions, Amazon adds your default location as a supply source. If you used a template to create additional locations, and Shipping Settings Automation (SSA) allows them, these locations are also added as supply sources.

To finish seller account setup:

Create new or update existing supply sources through the Supply Sources API or the Seller Central UI.
Provide location-specific inventory with the API.
Create or identify existing templates that SSA allows.
Assign the shipping template created or identified in Step 3 to the SKUs to which you added inventory. Do this for each location.
Set the DEFAULT inventory channel to 0.
Add the Selling Partner Insights role to your developer profile.

Mandatory APIs for multi-location inventory integration

Selling Partners must integrate the Supply Sources API, the Listings Items API, and the Feeds API to use multi-location inventory.

Create multi-location inventory shipping templates that are allowed by SSA in Seller Central

To learn how to create multi-location inventory shipping templates that are allowed by SSA, refer to Shipping Settings Automation.

Integrate the Supply Sources API

To learn how to use the multi-location inventory program with the Supply Sources API, refer to the Supply Sources API Use Case Guide.

Integrate the Listings Items API

Sellers can use the Listings Items API 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.

🚧
Caution
You must set the DEFAULT channel to 0. Failure to set the DEFAULT channel to 0 results in two listed offers: one multi-location inventory offer and one non-multi-location inventory offer. This issue does not affect the buyability of the offer, but the non-multi-location inventory offer might display inaccurate inventory and shipping timelines.

Use multi-location inventory 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

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

❗️
Warning
You must set Product Type and Path as follows:

Product Type = PRODUCT

Path = /attributes/fulfillment_availability

Failure to set these values can result in:

An error or a warning response

Data that might be ignored or might not reach the intended part of Amazon's system. This can affect related listing updates and inventory availability

Unexpected API behavior, such as an override of your data by default settings or issues with marketplace-specific operations

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

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

{
  "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 the Listings Items API to view your inventory

Sellers can use the Listings Items API to view the inventory count that is available at the supply source. Call the getListingsItem operation to return details about a listings item.

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).

Assign inventory for individual SKUs

Use the GET operation to find the quantity of an individual SKU for the default location. This example uses the ssnm001 SKU, which has a quantity of 3 at a single supply source.

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

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

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

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
        }
      ]
    }
  ]
}

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

Use the getListingsItem operation to submit the changes and retrieve details about fulfillmentAvailability.

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

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

The response confirms that the SKU is ssnm001 and that inventory is consolidated from two supply sources, Store A and Store B.

Verify that the quantity has been updated in Seller Central:

Log in to your Seller Central account.
In the upper-left corner, select the hamburger menu.
Choose Inventory and select Manage All Inventory.
Check the SKU number and related supply sources.

Retrieve the supply source ID that is used by selling partners through the Order Fulfillment feed

The Order Fulfillment feed directs Amazon to charge the buyer, credit the seller account, and notify the buyer that the order is shipped.

This feed provides the supply source ID that is used by a selling partner. To retrieve it, you must use the the Order Fulfillment feed's XML 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 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 added regularly to the Seller Central UI. If the CarrierCode value of the carrier you want to use is not mapped to the amzn-base XSD file, use the CarrierCode value of Other and provide the carrier name in the CarrierName field. Note that if you use this method, Amazon can't track package shipping updates.

After you create 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 shipped.

Make bulk updates

The Feeds API can make bulk updates. For an example feed with two SKUs that each contain 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 and ssnm002 SKUs.

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

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

{
  "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.

PUT: {{FeedUrl}}

{
  "header": {
    "sellerId": "A1PP0FEH11RW77",
    "version": "2.0"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "ssnm002",
      "operationType": "PATCH",
      "patches": {
        "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": {
        "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
          }
        ]
      }
    }
  ]
}

Create a feed.

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

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

{
  "feedId": "50037019429"
}

GET the feed document.

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

{
  "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.

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

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

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

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

To verify that the inventory quantity is updated in Seller Central:
1. Log in to your Seller Central account.
2. In the top-left corner, select the hamburger menu and expand it.
3. Choose Inventory and select Manage All Inventory.
4. Check the SKU number and related supply sources.

Troubleshooting

If you receive authorization errors, refer to Authorization Errors.

Updated 20 days ago

Multi-Location Inventory Integration Guide

🚧
Multi-location inventory is currently not available for sellers who:

Prerequisites

Mandatory APIs for multi-location inventory integration

Create multi-location inventory shipping templates that are allowed by SSA in Seller Central

Integrate the Supply Sources API

Integrate the Listings Items API

🚧
Caution

Use multi-location inventory to update your inventory

Path parameters

Header parameters

❗️
Warning

Use the Listings Items API to view your inventory

Path parameters

Query parameters

Assign inventory for individual SKUs

Retrieve the supply source ID that is used by selling partners through the Order Fulfillment feed

Confirm multiple orders through the Order Fulfillment feed

XML example

Make bulk updates

Assign inventory for multiple SKUs

Troubleshooting

🚧Multi-location inventory is currently not available for sellers who:

Prerequisites

Mandatory APIs for multi-location inventory integration

Create multi-location inventory shipping templates that are allowed by SSA in Seller Central

Integrate the Supply Sources API

Integrate the Listings Items API

🚧Caution

Use multi-location inventory to update your inventory

Path parameters

Header parameters

❗️Warning

Use the Listings Items API to view your inventory

Path parameters

Query parameters

Assign inventory for individual SKUs

Retrieve the supply source ID that is used by selling partners through the Order Fulfillment feed

Confirm multiple orders through the Order Fulfillment feed

XML example

Make bulk updates

Assign inventory for multiple SKUs

Troubleshooting

🚧
Multi-location inventory is currently not available for sellers who:

🚧
Caution

❗️
Warning