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 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:
- Configure a new supply source
- Configure the status of an existing supply source
- Retrieve the details of a configured supply source
- Update an existing supply source
- List all configured supply sources
- Practice onboarding an end-to-end seller with one SKU
- Retrieve the Order Fulfillment Feed
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.
- Create new or update existing supply sources via the Supply Sources API or 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
DEFAULT
inventory channel to0
. - 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:
- Authorization from the seller for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
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.
- Log in to your Seller Central account.
- Navigate to the settings icon in the top-right corner, then selectShipping Settings.
- Select the Locations tab.
- Choose Add Location to create a new supply source.
- To make changes to an existing Supply Source, select Edit on the right-hand side next to the supply source.
- 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. |
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. | 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
andendTime
are ISO 8601 formatted timestamps without dates. The format isHH: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 1 month ago