HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Supply Sources API v2020-07-01 Use Case Guide

Manage seller supply source configurations and capabilities using the Supply Sources API.

API Version: 2020-07-01

What is the Supply Sources API?

The Supply Sources API is used to configure and update information on seller supply sources, such as stores and warehouses. You can use the Supply Sources API to build applications that use location-level fulfillment capabilities and provide information about supply sources and location level inventory.

Key features

This use case guide provides tutorials on how to:

Prerequisites

Prior to using the Supply Sources API, your seller account must have permission to use Multi-Location Inventory (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 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. If you need to add or update supply sources, you can use the Supply Sources API or navigate to the Locations tab in Seller Central Shipping Settings.

  1. Create new or update existing supply sources via the Supply Sources API or 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 DEFAULT inventory channel to 0.
  6. Add the Selling Partner Insights role to your developer profile.

🚧

MLI is currently not available for the following sellers:

  • Sellers who are a part of the Buy Online Pickup in Store (BOPIS) program.
  • Sellers who use FBA inventory.
  • Sellers who manage their inventory via Seller Central.

Tutorial: Configure a new supply source

You can add a new supply source either by using the Supply Sources API or through Seller Central.

Prerequisites

To complete this tutorial, you will need:

Step 1. Configure a new supply source using the Supply Sources API

POST the Supply Sources API and pass the following parameters:

Request parameters

Parameter Description Required
supplySourceCode The seller provided unique supply source identifier.

Type: string

 Yes
alias The specific supply source. This field will be displayed to the buyer in relevant buyer facing use cases. Format must be in Store Name – City Name

Type: string

 Yes
address The specific address of the supply source.

Type: Address

 Yes

Address

The following table shows the child elements of the address element:

Element Description
name The name related to the address. This name should be displayed to the buyer. The format must be in Store Name – City Name

Type: string
addressLine1 An address field.

Type: string
addressLine2 An additional address field.

Type: string
addressLine3 An additional address field.

Type: string
city The specific address of the supply source.

Type: string
county The specific address of the supply source.

Type: string
district The specific address of the supply source.

Type: string
stateOrRegion The specific state or region of the address.

Type: string
postalCode The postal code of the address.

Type: string
countryCode The country code of the address.

Type: string
phone The phone number of the supply source address. This field will be displayed to the buyer in relevant buyer-facing use cases.

Type: string

Response

A successful response includes the following objects:

Name Description
supplySourceId The Amazon provisioned alpha numeric identifier of a supply source. The SupplySourceId is globally unique.

Type: string

Example response

{
  "address": {
    "name": "ABC Store - Milpitas",
    "addressLine1": "63 Ranch Dr",
    "countryCode": "US",
    "stateOrRegion": "CA",
    "addressLine2": "",
    "addressLine3": "",
    "city": "Milpitas",
    "county": "Santa Clara",
    "district": "",
    "postalCode": "95035",
    "phone": "1234567890"
  },
  "supplySourceCode": "TestRaghav123",
  "alias": "ABC Store - Milpitas"
}

Step 2. Configure a new supply source through Selling Central Shipping Settings

Alternatively, you can add a new supply source through Seller Central.

  1. Log in to your Seller Central account.
  2. Navigate to the settings icon in the top-right corner, then selectShipping Settings.
  3. Select the Locations tab.
  4. Choose Add Location to create a new supply source.
  5. To make changes to an existing Supply Source, select Edit on the right-hand side next to the supply source.
  6. Select Save.

Tutorial: Configure the status of an existing supply source

Step 1. Set the status of your store

PUT the status and pass the following parameters:

Request Parameters

Parameter Description Required
status Specify the status of the supply source. Valid values are Active and Inactive.

Type: string

 Yes

🚧

The store status is Inactive by default.

Selling Partners should set the status as Active when ready to go live.

Example response

{
    "supplySourceId": "353e4e48-6301-4d50-990e-43a86e8787a3",
    "supplySourceCode": "ss_ss005",
    "alias": "SS Store - Milpitas"
    "status": "Inactive"
    "address": {
        "name": "SS Store - Milpitas",
        "addressLine1": "63 Ranch Dr",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Milpitas",
        "county": "Santa Clara",
        "district": "",
        "stateOrRegion": "CA"
        "postalCode": "95035",
        "countryCode": "US",
    },
    "createdAt": "1.678741763E9",
    "updatedAt": "1.678741763E9"
}

Tutorial: Retrieve the details of a configured supply source

Step 1. Retrieve the supply source ID

GET the supplySourceId. No query parameters are required.

Response

A successful response includes the following objects:

Name Description
supplySourceId The Amazon provisioned alpha numeric identifier of a supply source. The SupplySourceId is globally unique.

Type: string
supplySourceCode The seller-provided unique supply source identifier.

Type: string
alias The name of the supply source. This field will be displayed to the buyer in relevant buyer facing use cases.

Type: string
status The store status. Possible values are Active, Inactive, and Archived.

Type: string
address The address of the supply source.

Type: Address
configuration The configuration of the supply source.

Type: SupplySourceConfiguration
capabilities The capabilities of the supply source.

Type: Capabilities
createdAt The date and time when the supply source was created.

Type: string
updatedAt The date and time when the supply source was updated.

Type: string

Tutorial: Update an existing supply source

Step 1. Set the supply source ID

PUT the supplySourceId and pass the following parameters:

Request parameters

Parameter Description Required
alias The specific name of the supply source. This field will be displayed to the buyer in relevant buyer facing use cases.

Type: string

 Yes
configuration The specific configuration of the supply source.

Type: SupplySourceConfiguration

 Yes
capabilities The specific capabilities of the supply source.

Type: Capabilities

 Yes

Configuration

The following table shows the child elements of the Configuration element:

Element Description
operationalConfiguration The operational configuration of the supply source.

Type: OperationalConfiguration
timezone The timezone in which the supply source operates. Refer to canonical time zone ID listed in RFC 6557.

Type: string
handlingTime For delivery use cases, the time required by seller to ship the item. For pickup use cases, the time needed by the seller to have the item ready for pickup.

Type: Duration

Handling time

🚧

HandlingTime is for us in the BOPIS program only.

The HandlingTime element cannot be used with MLI.

The following table shows the child elements of the HandlingTime element:

Element Description
value The handling time of the supply source.

Type: NonNegativeInteger
timeUnit The time units used to measure the handling time. Acceptable values are Minutes, Hours and Days.

Type: string

Operational configuration

The following table shows the child elements of the OperationalConfiguration element:

Element Description
contactDetails The contact details of the supply source.

Type: ContactDetails
operatingHoursByDay The operating hours of the supply source.

Type: OperatingHoursByDay
throughputConfig The throughput configuration of the supply source.

Type: ThroughputConfig

Contact details

The following table shows the child elements of the ContactDetails element:

Element Description
primary The contact details of the primary contact at the supply source.

Type: Primary

Primary

The following table shows the child elements of the Primary element:

Element Description
email The contact email address of the supply source. This field will be displayed to the buyer in relevant buyer facing use cases.

Type: string
phone The phone number of the supply source contact person.

Type: string

Operation hours by day

The following table shows the child elements of the OperatingHoursByDay element:

Element Description
monday The list of objects including [{"startTime": "string","endTime": "string"}].

Type: object
tuesday The list of objects including [{"startTime": "string","endTime": "string"}].

Type: object
wednesday The list of objects including [{"startTime": "string","endTime": "string"}].

Type: object
thursday The list of objects including [{"startTime": "string","endTime": "string"}].

Type: object
friday The list of objects including [{"startTime": "string","endTime": "string"}].

Type: object
saturday The list of objects including [{"startTime": "string","endTime": "string"}].

Type: object
sunday TThe list of objects including [{"startTime": "string","endTime": "string"}].

Type: object

🚧

Time formatting

The startTime and endTime are ISO 8601 formatted timestamps without dates. The format is HH:mm. For example, 12:30.

Throughput configuration

The following table shows the child elements of the ThroughputConfig element:

Element Description
throughputCap The throughputCap of the supply source.

Type: ThroughputCap

Throughput cap

The following table shows the child elements of the ThroughputCap element:

Element Description
value The throughputCap value.

Type: NonNegativeInteger
timeUnit The time unit of the throughputCap. Acceptable values are Minutes, Hours and Days.

Type: string

Capabilities

The following table shows the child elements of the Capabilities element:

Element Description
outbound The outbound capabilities of the supply source.

Type: OutboundCapability

Outbound

The following table shows the child elements of the Outbound element:

Element Description
isSupported When TRUE, the supply source supports outbound capability.

Type: Boolean
operationalConfiguration The structure of the operational configuration is the same as the one listed under the configuration parent entity. The values of the operational configuration at this level overrides the values mentioned at the configuration level.

Type: OperationalConfiguration
returnLocation The return address tied to the outbound of the supply source.

Type: ReturnLocation
deliveryChannel The operational configuration of the delivery channel. There will be a response only if the supply source supports delivery.

Type: DeliveryChannel
pickupChannel The operational configuration of the pickup channel. There will be a response only if the supply source supports pickup.

Type: PickupChannel

Return location

The following table shows the child elements of the ReturnLocation element:

Element Description
addressWithContact The contact information for the return capability.

Type: AddressWithContact
supplySourceId The Amazon provisioned alpha numeric identifier of a supply source. The SupplySourceId is globally unique.

Type: string

Address with contact

The following table shows the child elements of the AddressWithContact element:

Element Description
address The address of the return location.

Type: Address
contactDetails The contact details of the return location.

Type: ContactDetails

Delivery channel

The following table shows the child elements of the DeliveryChannel element:

Element Description
isSupported When TRUE, the seller can make deliveries from the supply source.

Type: Boolean
operationalConfiguration The structure of the operational configuration is the same as the one listed under the configuration parent entity. The values of the operational configuration at this level overrides the values mentioned at the configuration level.

Type: OperationalConfiguration

Pickup channel

The following table shows the child elements of the PickupChannel element:

Element Description
isSupported When TRUE, the seller can support in-store pickup from the supply source.

Type: Boolean
inventoryHoldPeriod The duration an item will be held at the supply source after it is ready for pick up.

Type: Duration
operationalConfiguration The structure of the operational configuration is the same as the one listed under the configuration parent entity. The values of the operational configuration at this level overrides the values mentioned at the configuration level.

Type: OperationalConfiguration

Inventory hold period

The following table shows the child elements of the InventoryHoldPeriod element:

Element Description
value The duration an item will be held at the supply source after it is ready for pickup.

Type: NonNegativeInteger
timeUnit The time units used to measure the inventory hold time. Acceptable values are Minutes, Hours and Days.

Type: string

Tutorial: Practice onboarding an end-to-end seller with one SKU

Step 1. Create the supply source

Example request

POST: {{baseUrl}}/supplySources/2020-07-01/supplySources

{
  "address": {
    "name": "SS Store - Milpitas",
    "addressLine1": "63 Ranch Dr",
    "countryCode": "US",
    "stateOrRegion": "CA",
    "addressLine2": "",
    "addressLine3": "",
    "city": "Milpitas",
    "county": "Santa Clara",
    "district": "",
    "postalCode": "95035",
    "phone": "1234567890"
  },
  "supplySourceCode": "ss_ss005",
  "alias": "SS Store - Milpitas"
}

Example response

{
  "supplySourceId": "353e4e48-6301-4d50-990e-43a86e8787a3",
  "supplySourceCode": "ss_ss005"
}

Step 2. Get the supply source

Example request

GET: {{baseUrl}}/supplySources/2020-07-01/supplySources/353e4e48-6301-4d50-990e-43a86e8787a3

Example response

{
    "supplySourceId": "353e4e48-6301-4d50-990e-43a86e8787a3",
    "supplySourceCode": "ss_ss005",
    "alias": "SS Store - Milpitas"
    "status": "Inactive"
    "address": {
        "name": "SS Store - Milpitas",
        "addressLine1": "63 Ranch Dr",
        "addressLine2": "",
        "addressLine3": "",
        "city": "Milpitas",
        "county": "Santa Clara",
        "district": "",
        "stateOrRegion": "CA"
        "postalCode": "95035",
        "countryCode": "US",
    },
    "createdAt": "1.678741763E9",
    "updatedAt": "1.678741763E9"
}

Step 3. Update the configuration status

Example request

PUT: {{baseUrl}}/supplySources/2020-07-01/supplySources/353e4e48-6301-4d50-990e-43a86e8787a3

Example response

{
  "alias": "SS Store - Milpitas",
  "configuration": {
    "operationalConfiguration": {
      "contactDetails": {
        "countryCode": {
          "primary": {
            "email": "[email protected]",
            "phone": "4813924781"
          }
        },
        "throughputConfig": {
          "throughputCap": {
            "value": 1,
            "timeUnit": "Days"
          },
          "throughputUnit": "ORDERS"
        },
        "handlingTime": {
          "value": 1,
          "timeUnit": "Hours"
        },
        "operatingHoursByDay": {
          "monday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "tuesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "wednesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "thursday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "friday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "saturday": {
            "startTime": "00:00",
            "endTime": "00:00"
          },
          "sunday": {
            "startTime": "00:00",
            "endTime": "00:00"
          }
        }
      },
      "timezone": "Africa/Accra"
    },
    "capabilities": {
      "outbound": {
        "isSupported": true,
        "operationalConfiguration": {
          "contactDetails": {
            "email": "[email protected]",
            "phone": "4813924781"
          }
        },
        "throughputConfig": {
          "throughputCap": {
            "value": 1,
            "timeUnit": "Days"
          },
          "throughputUnit": "ORDERS"
        },
        "handlingTime": {
          "value": 1,
          "timeUnit": "Hours"
        },
        "operatingHoursByDay": {
          "monday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "tuesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "wednesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "thursday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "friday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "saturday": {
            "startTime": "00:00",
            "endTime": "00:00"
          },
          "sunday": {
            "startTime": "00:00",
            "endTime": "00:00"
          }
        }
      }
    },
    "createdAt": "1.678741763E9",
    "updatedAt": "1.678741763E9"
  }
}

Step 4. Update the supply source status

Example request

PUT: {{baseUrl}}/supplySources/2020-07-01/supplySources/353e4e48-6301-4d50-990e-43a86e8787a3/status

Response

1

Step 5. Get the supply source

Example request

GET: {{baseUrl}}/supplySources/2020-07-01/supplySources/353e4e48-6301-4d50-990e-43a86e8787a3

Example response

{
  "supplySourceId": "353e4e48-6301-4d50-990e-43a86e8787a3",
  "supplySourceCode": "ss_ss005",
  "alias": "SS Store - Milpitas",
  "status": "Active",
  "address": {
    "name": "SS Store - Milpitas",
    "addressLine1": "63 Ranch Dr",
    "addressLine2": "",
    "addressLine3": "",
    "city": "Milpitas",
    "county": "Santa Clara",
    "district": "",
    "stateOrRegion": "CA",
    "postalCode": "95035",
    "countryCode": "US"
  },
  "configuration": {
    "operationalConfiguration": {
      "contactDetails": {
        "countryCode": {
          "primary": {
            "email": "[email protected]",
            "phone": "4813924781"
          }
        },
        "throughputConfig": {
          "throughputCap": {
            "value": 1,
            "timeUnit": "Days"
          },
          "throughputUnit": "ORDERS"
        },
        "handlingTime": {
          "value": 1,
          "timeUnit": "Hours"
        },
        "operatingHoursByDay": {
          "monday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "tuesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "wednesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "thursday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "friday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "saturday": {
            "startTime": "00:00",
            "endTime": "00:00"
          },
          "sunday": {
            "startTime": "00:00",
            "endTime": "00:00"
          }
        }
      },
      "timezone": "Africa/Accra"
    },
    "capabilities": {
      "outbound": {
        "isSupported": true,
        "operationalConfiguration": {
          "contactDetails": {
            "email": "[email protected]",
            "phone": "4813924781"
          }
        },
        "throughputConfig": {
          "throughputCap": {
            "value": 1,
            "timeUnit": "Days"
          },
          "throughputUnit": "ORDERS"
        },
        "handlingTime": {
          "value": 1,
          "timeUnit": "Hours"
        },
        "operatingHoursByDay": {
          "monday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "tuesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "wednesday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "thursday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "friday": {
            "startTime": "00:59",
            "endTime": "06:01"
          },
          "saturday": {
            "startTime": "00:00",
            "endTime": "00:00"
          },
          "sunday": {
            "startTime": "00:00",
            "endTime": "00:00"
          }
        }
      }
    },
    "createdAt": "1.678741763E9",
    "updatedAt": "1.678741763E9"
  }
}

Tutorial: Retrieve the Order Fulfillment

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

Updated about 2 months ago