Fulfillment Inbound API v2024-03-20 Use Case Guide
How to use the Fulfillment Inbound API
What is the Fulfillment Inbound API?
The Selling Partner API for Fulfillment Inbound lets you develop applications that create and update inbound plans to ship inventory to Amazon's fulfillment network, where Amazon can fulfill your customer's orders. You can also request lists of inbound shipments or inbound shipment items based on criteria you specify. After your inventory has been received in the fulfillment network, Amazon can fulfill your orders regardless of whether you are selling on Amazon's retail website or through other retail channels. Refer to the Fulfillment Inbound API reference for details about API operations and associated data types and schemas.
Key features
- Create an inbound shipment: The Fulfillment Inbound API accepts POST operations to create new inbound plans and select shipping modes and transportation options to determine the shipments.
- Retrieve details about inbound shipments: The Fulfillment Inbound API accepts GET operations to return detailed information about an existing shipment.
- Update inbound plans: The Fulfillment Inbound API accepts POST operations to update one or more individual attributes for an existing inbound plan, such as updating the inbound plan name or tracking ID.
- Delete inbound plans: The Fulfillment Inbound API accepts a PUT operation to delete an existing inbound plan.
- Interoperability: Plans created with the Fulfillment Inbound API can be accessed and edited on Amazon's UI (called Send to Amazon (STA)) once placement and transportation options are confirmed. You can also use the API to access plans that were created in STA after you confirm placement and transportation options.
Tip
Use
generatePlacementOptions
to generate new placement options andgenerateTransportationOptions
to generate new transportation options. If you switch from the API to STA before you confirm your options (withconfirmPlacementOption
andconfirmTransportationOptions
), new options are generated in STA and all previous options are discarded.
Terminology
- Amazon-partnered carrier: A carrier who has partnered with Amazon to provide discounted shipping rates.
- Non-Amazon-partnered carrier: A carrier who has not partnered with Amazon to provide discounted shipping rates.
- Small parcel shipment: Units packed in individual boxes that are individually labeled for delivery.
- Less Than Truckload/Full Truckload (LTL/FTL) shipment: Combines individual boxes on pallets for delivery. The truck might contain shipments to other destinations.
Considerations
The following are not supported, but will be supported in the future:
- Creating shipments for the following destination marketplaces:
- Mexico
- Brazil
- Poland
- Egypt
- Turkey
- Saudi Arabia
- United Arab Emirates
- India
- Selecting prep category for a SKU
This use case guide mentions two v0 operations that are needed for end-to-end shipment creation: getLabels
and getBillOfLading
. These operations are not deprecated. You must continue to use these operations to print your box label, pallet label, or bill of lading.
The following v0 operations are not deprecated:
getLabels
getBillOfLading
getPrepInstructions
getShipments
getShipmentItemsByShipmentId
getShipmentItems
Fulfillment Inbound shipment workflow
The following diagram shows the steps to ship inventory to Amazon's fulfillment network. This is an illustrative example and does not include all of the optional operations.
Ship inventory into Amazon's Fulfillment Network
There are two processes that a seller can follow to create a shipment, which differ based on whether the seller knows how their cartons will be packed at the time of shipment creation. In most cases, we expect that sellers would have this information, but there are situations where this information wouldn't be readily available.
Note that the process for creating a shipment when the carton-level information is not known upfront is only available for LTL shipments at this time. This document provides the steps you can follow to ship inventory to Amazon's fulfillment network using either of these processes.
Tutorial: Creating a shipment when the seller knows the carton-level information up-front
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API applications for more information.
- Approval for the Amazon Fulfillment role and the Product Listing role in your developer profile.
- The Amazon Fulfillment role and Product Listing role selected in the App registration page for your application.
- To have created your listings and understand whether your items are eligible to be shipped to Amazon's fulfillment network (instructions included in optional step section)
Step 1. Create an Inbound Plan
Create an Inbound Plan by calling the asynchronous createInboundPlan
operation. An Inbound Plan represents a collection of items that you intend to inbound into Amazon's fulfillment network. By calling the createInboundPlan
operation, a seller must specify the following:
- The address from which the inbound shipments will be sent
- The marketplace where the product would be shipped
- A summary of the items that they intend to inbound.
The item summary must include MSKU, quantity, and an indication of who will prepare / label the item. Note that AMAZON
can only be selected as the label owner if you are enrolled in the FBA Label Service. For more information about the FBA Label Service, refer to Seller Central Help for your marketplace.
Make sure each item you're shipping conforms to Amazon's product packaging requirements. For more information, refer to Packaging and Prep Requirements in Seller Central Help. For more information about Amazon's product packaging requirements for your marketplace, refer to Seller Central URLs. Note that sellers can set the Prep Category for SKUs on Send to Amazon. This can be done one by one or up to 25 at a time. This is a one-time activity per SKU that carries over to all future inbound plans.
Note
Multiple expiration dates per SKU on a single inbound plan is not supported. To send a SKU with multiple expiration dates to the fulfillment network, you need to create multiple plans.
Optionally, a seller can include each item's expiration date and manufacturing lot code. A successful response includes an inboundPlanId
that uniquely identifies the inbound plan, synonymous with the concept of "workflow ID", which is generated on Send to Amazon (the shipment creation workflow on Seller Central).
Note
This operation generates initial shipment IDs for the shipments within each inbound plan. These IDs are different from the
shipmentConfirmationIDs
that are generated with theconfirmPlacementOption
operation. TheshipmentConfirmationID
is the identifier that appear on labels (for example,FBA1234ABCD
). Both of these types of shipment IDs can be retrieved with thegetShipment
operation.
Body parameters
Name | Description | Required |
---|---|---|
destinationMarketplaces |
Specifies the marketplace where the product would be shipped to. Type: < string > array |
Yes |
items |
Items included in this plan. Type: < |
Yes |
name |
The name for the inbound plan. If one isn't provided, a default name is provided. Type: string |
No |
sourceAddress |
Specific details to identify a place. Type: |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans
{
"destinationMarketplaces" : [ "ATVPDKIKX0DER" ],
"items" : [ {
"expiration" : "2024-01-01",
"labelOwner" : "AMAZON",
"manufacturingLotCode" : "manufacturingLotCode",
"msku" : "Sunglasses",
"prepOwner" : "AMAZON",
"quantity" : 10
} ],
"name" : "My inbound plan",
"sourceAddress" : {
"addressLine1" : "123 example street",
"addressLine2" : "Floor 19",
"city" : "Toronto",
"companyName" : "Acme",
"countryCode" : "CA",
"email" : "[email protected]",
"name" : "name",
"phoneNumber" : "1234567890",
"postalCode" : "M1M1M1",
"stateOrProvinceCode" : "ON"
}
}
Response
A successful response includes the following elements:
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
operationId |
UUID for the given operation. Type: string |
Yes |
Response example
{
"operationId": "operationId1234",
"inboundPlanId": "PlanID1234"
}
Check the status of a call
Check the status of an inbound request by using the getInboundOperationStatus
operation. For asynchronous operations, this operation provides the processing status. We omit this step for other asynchronous operations in this tutorial. By calling getInboundOperationStatus
, a seller passes the operationId
, which is a Universal Unique Identifier (UUID) for the operation.
A successful response includes the status of the request and any non-blocking errors associated with the request. Non-blocking errors are warnings that can be ignored (for example, when the address is suspected to be wrong, but progression is allowed anyway).
Path parameters:
Name | Description | Required |
---|---|---|
operationId |
Identifier to an asynchronous operation. Type: string |
Yes |
Request example
GET /inbound/fba/2024-03-20/operations/{operationId}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operation |
The operation associated with the operationId .Type: string |
operationId |
Operation ID returned by the asynchronous API call. Type: string |
operationProblems |
Problems in the processing of the asynchronous operation. < OperationProblem > array |
operationStatus |
The status of an operation. Type: OperationStatus |
Response example
{
"operation": "string",
"operationId": "string",
"operationProblems": [
{
"code": "Error code 1234",
"message": "Box volume does not meet the expected minimum cubic cm 144,815",
"details": "Additional error details",
"severity": "WARNING"
}
],
"status": "SUCCESS",
}
Step 2. Determine which SKUs can be packed together
This step is necessary to determine which items can be packed together. Some items cannot be packed together due to differing handling or fulfillment center requirements. There might be a discount for further separating items.
Note
There are only discounted options for SPD shipments in the EU. These discounted options can include additional requirements, including that each package must weigh less than 15 kilograms.
To determine which SKUs can be physically packed together, use the following operations:
A PackingGroup
represents a set of SKUs that can be packed together. SKUs that cannot be packed together go into different pack groups. For example, SKUs that are classified as dangerous goods cannot be packed with other SKUs, because dangerous goods SKUs are shipped to special fulfillment centers that can receive them safely. Other factors that determine which SKUs can and cannot be packed together include SKU weights and dimensions, prep and labelling requirements, and barcode requirements.
The PackingOptions
object represents the set of options for how items are mapped to packing groups. Each PackingOption
includes a set of PackingGroups
, which each contain a list of SKUs. Each of these options can have discounts or fees associated with them. Also, each option can be limited to a subset of all possible shipping modes. These packing operations enable the seller to review and select an option.
Step 2a. Generate packing options
First, generate packing options with the generatePackingOptions
operation.
Path parameters
Name | Description |
---|---|
inboundPlanId required |
The inboundPlanId identifies an inbound plan.Type: string |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string",
"inboundPlanId": "string"
}
Step 2b. List packing options
Next, review a list of the packing options with the listPackingOptions
operation. Packing options contain sets of pack groups that a seller can choose, along with additional information that can help a seller choose between these options. Additional information includes fees/discounts associated with each option, shipping modes supported by each option, and the expiration date of each option.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of packing options to return in the response that matches the given query. Minimum : 1 Maximum : 20 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
packingOptions |
Specifies the pack groups, fees/discounts, and supported shipping modes for each option. Type: < PackingOption > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"packingOptions": [
{
"inboundPlanId": "string",
"packingOptionId": "string",
"packingGroups": [
"string"
],
"fees": [
{
"currency": {
"code": "string",
"amount": 0
},
"type": "FEE",
"target": "OUTBOUND_PER_SHIPMENT",
"description": "string"
}
],
"discounts": [
{
"currency": {
"code": "string",
"amount": 0
},
"type": "FEE",
"target": "OUTBOUND_PER_SHIPMENT",
"description": "string"
}
],
"expiration": "2019-08-24T14:15:22Z",
"status": "OFFERED",
"supportedShippingModes": [
{
"shippingSolution": "AMAZON_PARTNERED_CARRIER",
"shippingMode": "GROUND_SMALL_PARCEL"
}
]
}
]
}
Step 2c. List items in each packing option
To view the items in each packing group, use the listPackingGroupItems
operation.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
packingOptionId |
Identifier to a packing option. | Yes |
packingGroupId |
Identifier to a packing group. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of packing group items to return in the response that matches the given query. Minimum : 1 Maximum : 100 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingGroups/{packingGroupId}/items
Response
A successful response includes the following elements:
Name | Description |
---|---|
items |
Provides the base items in the inbound plan with quantity and prep owner identification. Type: < Item > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "AMAZON",
"quantity": 1,
"prepOwner": "AMAZON"
}
]
}
Step 2d. Select a packing option
Choose a packing option with the confirmPackingOption
operation.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
packingOptionId |
Identifier to a packing option. | Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions/{packingOptionId}/confirmation
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 3. Provide box content information
To provide information related to the items that will be packed into each box, use the setPackingInformation
operation. Providing this information ensures that the shipment splits generated in the subsequent step (generatePlacementOptions
) are accurate. If no box information is provided at this step, the shipment splits generated in the next step are based only on the unit information passed to Amazon as part of createInboundPlan
. By calling setPackingInformation
, a seller must pass the following information for each box that they intend to inbound:
- Packing group ID
- Box content information source
- Box contents (items, item quantities, prep/label owners for each item)
- Box information (dimensions, weight, and quantity of boxes)
Note
If a seller provides box packing information using
setPackingInformation
, generates placement options, and then edits their box packing information usingsetPackingInformation
, then the seller needs to callgeneratePlacementOptions
again prior to callingconfirmPlacementOption
. If a seller inputs their box packing information usingsetPackingInformation
and then decides that they want to discard this information entirely, they need to start a new inbound plan withcreateInboundPlan
. Discarding packing information is not currently supported.
Box content information source indicates how the seller intends to provide box content information, which could be through one of three options:
- Populating the Contents field (
BOX_CONTENT_PROVIDED
) - Paying Amazon a fee to enter this information during the receiving process (
MANUAL_PROCESS
) - Affixing 2D barcodes to the boxes (
BARCODE_2D
)
The seller must also provide box dimensions, box weight, and the quantity of each box. When boxAttribute
is set toBARCODE_2D
or MANUAL_PROCESS
:
- You don't need to provide SKUs and quantities.
- You must leave
items
empty (provide anull
value).
A successful response includes the operationId
that can be used to determine the status of the operation using getInboundOperationStatus
.
Note
In this flow, pass in the
PackingGroupId
but omit theShipmentId
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to setPackingInformation .Type: SetPackingInformationRequest |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingInformation
{
"packageGroupings": [
{
"packingGroupId": "string",
"boxes": [
{
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"boxId": "string",
"items": [
{
"msku": "string",
"quantity": 1,
"expiration": "string",
"prepOwner": "AMAZON",
"labelOwner": "AMAZON",
"manufacturingLotCode": "string"
}
],
"contentInformationSource": "BOX_CONTENT_PROVIDED"
}
]
}
]
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 4. Generate and view options for destination fulfillment centers
Generate placement options for an inbound plan by calling the generatePlacementOptions
operation. The PlacementOptions
object represents the set of available placement options for an inbound plan, where each placement option describes the destination FCs and shipping options for each item in your inbound plan. These options help reduce the time it takes to receive a seller's items and make them available for sale (refer to Seller Central Help for more details).
Some of your options can include multiple destinations (refer to Seller Central Help for details). Each option can include fees or discounts, which are determined using an algorithm when your shipment is being created, and is not calculated using a set rate. The algorithm for the rebate value and the ship-to location uses multiple factors to optimize your shipments, including expected volume, the availability of carrier appointments, and fulfillment speed. The rebate that your shipment is eligible for is provided during shipment creation.
The terms and conditions can change. Review the current Seller Central terms and conditions, including the Amazon Services Business Solutions Agreement.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to generatePlacementOptions . |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions
{
}
Response
A successful response includes the following elements:
Name | Description | Required |
---|---|---|
operationId |
UUID for the given operation. Type: string |
Yes |
Response example
{
"operationId": "string"
}
To view the options for shipment splits, call the listPlacementOptions
operation. This operation provides the list of available placement options, which include:
- A placement option ID
- The option status ("offered" or "accepted")
- Any fees/discounts associated with this option
- The expiration date of the option
- The shipment IDs associated with each option
When a placement option expires, you must regenerate placement options by calling generatePlacementOption
. The placement option ID is required to generate transportation options with generateTransportationOptions
, while shipment IDs are used to understand the contents of each shipment using getShipment
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of placement options to return in the response that matches the given query. Minimum : 1 Maximum : 20 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
placementOptions |
Placement options generated for the inbound plan. Type: < PlacementOption > array |
Response example
{
"pagination": {
"nextToken": "string"
},
"placementOptions": [
{
"inboundPlanId": "string",
"placementOptionId": "string",
"status": "OFFERED",
"fees": [
{
"currency": {
"code": "string",
"amount": 0
},
"type": "FEE",
"target": "OUTBOUND_PER_SHIPMENT",
"description": "string"
}
],
"discounts": [
{
"currency": {
"code": "string",
"amount": 0
},
"type": "FEE",
"target": "OUTBOUND_PER_SHIPMENT",
"description": "string"
}
],
"expiration": "2019-08-24T14:15:22Z",
"shipmentIds": [
"string"
]
}
]
}
Step 5. Input transportation data and generate transportation options
Generate transportation options with the generateTransportationOptions
operation. A transportation option represents the list of shipping mode and carrier options that are available for each shipment within each placement option. By calling generateTransportationOptions
, a seller must pass the following information:
- Placement option ID
- Shipment ID
- Ready to ship date
- Ship from address
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
Identifier to an inbound plan. Type: string of 38 characters. Format: `^[a-zA-Z0-9-]*$` |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to generateTransportationOptions . |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions
{
"placementOptionId": "string",
"shipmentTransportationConfigurations": [
{
"shipmentId": "string",
"readyToShipWindow": {
"start": "2019-08-24T14:15:22Z"
},
"contactInformation": {
"phoneNumber": "string",
"email": "string",
"name": "string"
},
"palletInformation": {
"pallets": [
{
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"stackability": "STACKABLE"
}
],
"freightClass": "string",
"declaredValue": {
"code": "str",
"amount": 0
}
}
}
]
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 6. Generate delivery window options with the generateDeliveryWindowOptions
operation.
generateDeliveryWindowOptions
operation.Delivery windows are seven-day periods during which a seller can deliver their shipment to the destination fulfillment center. The window is used to provide a shipment's expected arrival date and time at an Amazon fulfillment center. An available delivery window option is necessary for all shipments that don't have an appointment slot with a fulfillment center. For example, all shipments through non-partnered carriers need a confirmed delivery window.
Important
Sellers must confirm transportation options for all shipment types. For non-Amazon partnered shipments, they must also specify a delivery window.
generateDeliveryWindowOptions
requires the seller to pass the shipmentID
for the shipment for which they intend to generate delivery windows.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment for which you want to generate delivery window options. | Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions
Response
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 7. Review shipment splits and transportation options
Review shipment and transportation options by calling the listPlacementOptions
, listTransportationOptions
, and getShipment
operations.
listPlacementOptions
provides the list of available placement options, which includes a placement option ID, the status of the option (that is, offered vs. accepted), any fees/discounts associated with this option, the expiration date of the option, and the shipment IDs associated with each option.
To call listTransportationOptions
, a seller needs to pass the placement option ID and shipment ID for which they want to view transportation options. A successful response includes all available transportation quotes for all available ship modes and carrier options. Shipping modes include:
- Ground small parcel
- Less-than-truckload freight
- Full truckload freight (palletized)
- Full truckload freight (non-palletized)
- Less than container load ocean
- Full container load ocean
- Air small parcel
- Air small parcel express
Carrier options include Amazon-partnered and non-partnered carriers. Quotes include:
- Cost
- A void window (the period where a seller can cancel a shipment and receive a refund for their transportation quote)
- Expiration
In regions where fulfillment center appointments are mandatory (for example, India), we provide available appointment slots.
Where the Partnered Carrier Program is available, sellers can take advantage of discounted rates by using an Amazon-partnered carrier for their inbound shipments. To use an Amazon-partnered carrier for an inbound shipment, select the transportation option where shippingSolution
is AMAZON_PARTNERED_CARRIER
. Note that before using an Amazon-partnered carrier for an inbound shipment, you must read the Seller Central Help about Amazon's Partnered Carrier Program to help ensure that you successfully follow the program instructions and guidelines (Europe) (US). In the EU region, before using an Amazon-partnered carrier for an inbound shipment, you must first review and accept the terms and conditions of the carrier and the terms and conditions of Amazon's Partnered Carrier Program. You can do this on Seller Central. If you attempt to use Amazon Selling Partner APIs to create an inbound shipment using an Amazon-partnered carrier before accepting these terms and conditions, the service returns an error. If a seller is not interested in participating in the Partnered Carrier Program, they are also able to view transportation options that allow them to "choose your own carrier" along with available shipping modes.
Path parameters
Type | Name | Description |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Type | Name | Description |
---|---|---|
pageSize |
Number of transportation options to return in the response that matches the given query. Minimum : 1 Maximum : 20 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
placementOptionId |
The placement option to get transportation options for. | No |
shipmentId |
The shipment to get transportation options for. Either placementOptionId or shipmentId must be specified. |
No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
transportationOptions |
Transportation options generated for the placement option. Type: < TransportationOption > array |
Response example
{
"pagination": {
"nextToken": "string"
},
"transportationOptions": [
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"transportationOptionId": "string",
"shippingSolution": "AMAZON_PARTNERED_CARRIER",
"carrier": {
"name": "string",
"alphaCode": "string"
},
"shippingMode": "GROUND_SMALL_PARCEL",
"quote": {
"cost": {
"code": "string",
"amount": 0
},
"voidableUntil": "2019-08-24T14:15:22Z",
"expiration": "2019-08-24T14:15:22Z"
},
"appointmentSlot": {
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
}
}
]
}
Review available delivery window options for each shipment within an inbound plan using the listDeliveryWindowOptions
operation. To make this call, a seller passes the shipmentID
. A successful response provides the startDate
and endDate
for each available delivery window and the level of congestion (availabilityType
) for each option.
Important
Sellers must confirm transportation options for all shipment types. For non-Amazon partnered shipments, they must also specify a delivery window.
Each option has an expiration date (validUntil
). You must confirm the delivery before this date. If you don't confirm the window by the validUntil
date, you must generate a new window using listDeliveryWindowOptions
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment you want to confirm the delivery window option for. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
The number of delivery window options to return in the response that matches the given query. | No |
paginationToken |
The shipment you want to confirm the delivery window option for. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
deliveryWindowOptions |
Delivery window options generated for the placement option. Type: < DeliveryWindowOption > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"deliveryWindowOptions": [
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"deliveryWindowOptionId": "string",
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"availabilityType": "string",
"validUntil": "2019-08-24T14:15:22Z"
}
]
}
Review details related to the contents of a shipment within an inbound plan using the getShipment
operation. To call getShipment
, a seller needs to pass the inbound plan ID and shipment ID. A successful response includes the following:
- Placement option ID
- Shipment confirmed ID (the ID that shows up on labels)
- Shipment ID (the identifier for a shipment prior to the
confirmPlacementOption
operation) - Amazon reference ID (identifier for scheduling fulfillment center appointments for truck deliveries)
- Selected transportation option ID
- Name
- Source
- Destination FC
- Ship date
- Estimated delivery date
- Status
- Tracking details
- Pallet information
- Contact information
- Destination region
- FC appointment details
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. | Yes |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}
Response
A successful response includes the following elements:
Name | Description |
---|---|
amazonReferenceId |
A unique identifier created by Amazon that identifies this Amazon-partnered, Less Than Truckload/Full Truckload (LTL/FTL) shipment. Type: string |
contactInformation |
The seller's contact information. Type: ContactInformationWithName |
dates |
Specifies the dates that the seller expects their shipment will be shipped and delivered. Type: Dates |
destination |
The Amazon fulfillment center address and warehouse ID. Type: ShipmentDestination |
selfShipAppointmentDetails |
List of self ship appointment details. Type: < SelfShipAppointmentDetails > array |
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
name |
The name of the shipment. Type: string |
palletInformation |
Pallet information, including weight, dimensions, quantity, stackability, freight class, and declared value. Type: PalletInformation |
placementOptionId |
Identifier to a placement option. A placement option represents the shipment splits and destinations of SKUs. Type: string |
selectedTransportationOptionId |
Identifier to a transportation option. A transportation option represent one option for how to send a shipment. Type: string |
shipmentConfirmationId |
The confirmed shipment ID which shows up on labels (for example, FBA1234ABCD ).Type: string |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. Type: string |
source |
Specifies the 'ship from' address for the shipment. Type: ShipmentSource |
status |
Possible statuses of a shipment. Type: ShipmentStatus |
trackingDetails |
The tracking number of the package, provided by the carrier. For LTL shipments, either freight bill number can be either the freight bill number or the PRO number. Type: TrackingDetails |
Response example
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"shipmentConfirmationId": "string",
"amazonReferenceId": "string",
"selectedTransportationOptionId": "string",
"name": "string",
"source": {
"sourceType": "SELLER_FACILITY",
"address": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
}
},
"destination": {
"destinationType": "AMAZON_OPTIMIZED",
"address": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
},
"warehouseId": "string"
},
"dates": {
"readyToShipWindow": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"editableUntil": "2019-08-24T14:15:22Z"
},
"deliveryWindow": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"editableUntil": "2019-08-24T14:15:22Z"
}
},
"status": "ABANDONED",
"trackingDetails": {
"ltlTrackingDetail": {
"freightBillNumber": [
"string"
],
"billOfLadingNumber": "string"
},
"spdTrackingDetail": {
"spdTrackingItems": [
{
"boxId": "string",
"trackingId": "string",
"trackingNumberValidationStatus": "VALIDATED"
}
]
}
},
"palletInformation": {
"pallets": [
{
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"stackable": true
}
],
"freightClass": "NONE",
"declaredValue": {
"code": "string",
"amount": 0
}
},
"contactInformation": {
"phoneNumber": "string",
"email": "string",
"name": "string"
},
"selfShipAppointmentDetails": [
{
"appointmentId": 0,
"appointmentSlotTime": {
"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"appointmentStatus": "string"
}
]
}
Step 8. Select shipping option
Select shipment option (that is, shipment splits) with the confirmPlacementOption
operation. This operation selects the placement splits for an inbound plan and creates confirmed shipment IDs for shipments within the inbound plan. The shipmentConfirmationID
is the shipment identifier that appears on labels (for example, FBA1234ABCD
). This ID is different from the shipment ID that is generated with createInboundPlan
, which is used as an input to other operations, such as getShipment
. This option cannot be reversed after it is selected. To call confirmPlacementOption
, a seller must pass the inbound plan ID and the selected placement option ID.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
placementOptionId |
Identifier to a placement option. A placement option represents the shipment splits and destinations of SKUs. | Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions/{placementOptionId}/confirmation
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 9. Select transportation options
Select delivery windows for each shipment within a plan using the confirmDeliveryWindowOptions
operation. To call this operation, pass the shipmentID
and deliveryWindowOptionId
(provided by listDeliveryWindowOptions
).
You must confirm a placement option for the shipment before you call this operation. After you confirm the delivery window, new delivery window options cannot be generated. However, you can update the selected delivery window option before shipment closure. For all transportation options that have the program DELIVERY_WINDOW_REQUIRED
, you must confirm a delivery window before you confirm the transportation option. If you need to update your delivery window after you confirm the transportation option, you can call confirmDeliveryWindow
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment you want to confirm the delivery window option for. | Yes |
deliveryWindowOptionId |
The ID of the delivery window option to be confirmed. | Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/deliveryWindowOptions/confirmation
{
"transportationSelections": [
{
"shipmentId": "string",
"transportationOptionId": "string",
"contactInformation": {
"phoneNumber": "string",
"email": "string",
"name": "string"
}
}
]
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
This mandatory step allows you to select transportation options for each shipment within an inbound plan using the confirmTransportationOptions
operation. For Amazon-partnered transportation options, this operation confirms that the seller accepts the Amazon-partnered shipping estimate, agrees to allow Amazon to charge their account for the shipping cost, and requests that the Amazon-partnered carrier ships the inbound shipment. Before this call, a seller must confirm a placement option for their inbound plan. To call confirmTransportationOptions
, a seller must pass the shipment ID, selected transportation option ID, and contact information (needed for partnered carriers for LTL shipments). When a transportation option is confirmed, new transportation options cannot be generated or confirmed for an inbound plan. You must confirm a transportation option before printing labels.
Note
If a seller confirms the transportation request, then decides they don't want the Amazon-partnered carrier to ship the inbound shipment, they can use
cancelInboundPlan
to cancel the transportation request. For Small Parcel shipments, the seller has 24 hours after confirming a transportation request to void the request. For Less Than Truckload/Full Truckload (LTL/FTL) shipments, the seller has one hour after confirming a transportation request to void the request. After the relevant time period expires, the seller's account is charged for the shipping cost.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
confirmTransportationOptions request.Type: ConfirmTransportationOptionsRequest |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions/confirmation
{
"transportationSelections" : [ {
"contactInformation" : {
"email" : "[email protected]",
"name" : "John Smithy",
"phoneNumber" : "1234567890"
},
"deliveryWindow" : {
"start" : "2024-01-01T00:00Z"
},
"shipmentId" : "sh1234abcd-1234-abcd-5678-1234abcd5678",
"transportationOptionId" : "to1234abcd-1234-abcd-5678-1234abcd5678"
} ]
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 10. Printing labels
Call the getLabels
operation to request unique shipping labels for your inbound shipments. Each shipping label returned by the getLabels
operation should be affixed to the package in the shipment that it corresponds to, so the labels indicate the package contents. This helps to ensure that your shipment is processed at the Amazon fulfillment center quickly and accurately.
Refer to Request shipping labels for your inbound shipment for detailed instructions.
Step 11. Send your shipments to Amazon's fulfillment network
Send your shipments to Amazon's fulfillment network using an Amazon-Partnered carrier or a non-Amazon-Partnered carrier that is registered with Amazon. For more information about sending shipments to Amazon's fulfillment network, refer to the Seller Central Help for your marketplace.
As you prepare your shipment, you can retrieve all of the box-level information that you have entered for an inbound plan using the listInboundPlanBoxes
operation.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of packages to return in the response that matches the given query. Minimum : 1 Maximum : 1000 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/boxes
Response
A successful response includes the following elements:
Name | Description |
---|---|
boxes |
The boxes in an inbound plan. Type: < ListPackagesBox > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"boxes": [
{
"packageId": "string",
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 0,
"boxId": "string",
"templateName": "string",
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "AMAZON",
"quantity": 1,
"expiration": "string",
"manufacturingLotCode": "string",
"prepInstructions": [
{
"prepType": "string",
"prepOwner": "AMAZON",
"fee": {
"code": "string",
"amount": 0
}
}
]
}
],
"shipmentId": "string",
}
]
}
Step 12. Providing tracking information
After sending a shipment to Amazon's fulfillment network using a non-partnered carrier, a seller must share the tracking ID using the updateShipmentTrackingDetails
operation. To call this operation, a seller must pass the shipment ID and tracking details for their less-than-truckload or small parcel shipment. For less-than-truckload shipments, the seller must provide a PRO number (also known as Freight Bill number) and can optionally provide a BOL number. For small parcel shipments, the seller must share an array of box IDs and associated tracking IDs.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
UpdateShipmentTrackingDetails request.Type: UpdateShipmentTrackingDetailsRequest |
Yes |
Request example
PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/trackingDetails
{
"trackingDetails": {
"ltlTrackingDetail": {
"freightBillNumber": [
"string"
],
"billOfLadingNumber": "string"
},
"spdTrackingDetail": {
"spdTrackingItems": [
{
"boxId": "string",
"trackingId": "string"
}
]
}
}
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Tutorial: Creating a shipment when the seller does not know the carton level information up-front
Step 1. Create an Inbound Plan
Note
The process for creating a shipment when the carton-level information is not known upfront is only available for LTL shipments.
Create an Inbound Plan by calling the asynchronous createInboundPlan
operation. An Inbound Plan represents a collection of inbound shipments that contain items you intend to inbound into Amazon's fulfillment network. By calling the createInboundPlan
operation, a seller must specify:
- The address from which the inbound shipments will be sent
- The marketplace where the product would be shipped
- Contact information (needed for partnered carriers for LTL shipments)
- A summary of the items they intend to inbound
The item summary must include MSKU, quantity, and an indication of who will prepare/label the item. Note that AMAZON_LABEL
is available only if you are enrolled in the FBA Label Service. For more information about the FBA Label Service, refer to the Seller Central Help for your marketplace.
Make sure each item you ship conforms to Amazon's product packaging requirements. For more information, refer to Packaging and Prep Requirements in Seller Central Help. For more information about Amazon's product packaging requirements for your marketplace, refer to Seller Central URLs. You can set the Prep Category for SKUs on Send to Amazon Step 1. You can do this one at a time or up to 25 at a time. This is a one-time activity per SKU that carries over to all future inbound plans.
Note
Multiple expiration dates per SKU on a single inbound plan is not supported. To send a SKU with multiple expiration dates to the fulfillment network, you need to create multiple plans.
Optionally, a seller can include each item's expiration date and manufacturing lot code. A successful response includes an inboundPlanId
, which is a unique identifier for the inbound plan, synonymous with the concept of "workflow ID", which is generated on Send to Amazon (the shipment creation workflow on Seller Central).
Note
createInboundPlan
generates initial shipment IDs for the shipments within each inbound plan. These IDs are different from theshipmentConfirmationIDs
that are generated with theconfirmPlacementOption
operation. TheshipmentConfirmationID
is the identifier that appears on labels (for example,FBA1234ABCD
). Both of these types of shipment IDs can be retrieved with thegetShipment
operation.
Body parameters
Name | Description | Required |
---|---|---|
contactInformation |
The Seller's contact information. Type: ContactInformation |
Yes |
destinationMarketplaces |
Specifies the marketplace where the product would be shipped to. Type: < string > array |
Yes |
items |
Items included in this plan. Type: < ItemInput > array |
Yes |
name |
Name for the Inbound Plan. If one isn't provided, a default name is provided. minLength : 1 maxLength : 40 Type: string |
No |
sourceAddress |
Specific details to identify a place. Type: Address |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans
{
"contactInformation" : {
"email" : "[email protected]",
"name" : "name",
"phoneNumber" : "1234567890"
},
"destinationMarketplaces" : [ "ATVPDKIKX0DER" ],
"items" : [ {
"expiration" : "2024-01-01",
"labelOwner" : "AMAZON",
"manufacturingLotCode" : "manufacturingLotCode",
"msku" : "Sunglasses",
"prepOwner" : "AMAZON",
"quantity" : 10
} ],
"name" : "My inbound plan",
"sourceAddress" : {
"addressLine1" : "123 example street",
"addressLine2" : "Floor 19",
"city" : "Toronto",
"companyName" : "Acme",
"countryCode" : "CA",
"email" : "[email protected]",
"name" : "name",
"phoneNumber" : "1234567890",
"postalCode" : "M1M1M1",
"stateOrProvinceCode" : "ON"
}
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "operationID1234",
"inboundPlanId": "PlanID1234"
}
Check the status of a call
Check the status of an inbound request by using the getInboundOperationStatus
operation. For asynchronous operations, this operation provides the processing status. We omit this step for other asynchronous operations in this tutorial. By calling getInboundOperationStatus
, a seller passes the operationId
, which is a Universal Unique Identifier (UUID) for the operation. A successful response includes the status of the request and can include a list of errors associated with the request.
Path parameters
Name | Description | Required |
---|---|---|
operationId |
Unique request reference identifier. Type: string |
Yes |
Request example
GET /inbound/fba/2024-03-20/operations/{operationId}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operation |
The operation associated with the operationId .Type: string |
operationId |
Operation ID returned by the asynchronous API call. Type: string |
operationProblems |
Problems in the processing of the asynchronous operation. < OperationProblem > array |
operationStatus |
The status of an operation. Type: OperationStatus |
Response example
{
"operation": "string",
"operationId": "string",
"operationProblems": [
{
"code": "Error code 1234",
"message": "Box volume does not meet the expected minimum cubic cm 144,815",
"details": "Additional error details",
"severity": "WARNING"
}
],
"status": "SUCCESS",
}
Step 2. Generate and view options for destination fulfillment centers
Generate and view placement options for an inbound plan by calling the generatePlacementOptions
, listPlacementOptions
, and getShipment
operations.
Warning
Sellers cannot provide packing information using Send to Amazon after confirming placement options. They will not be able to access API-created shipments on Send to Amazon during this step.
The placementOptions
object represents the set of available placement options for an inbound plan, where each placement option describes the destination FCs and shipping options for each item in your inbound plan. These options are designed to help reduce the time that it takes to receive a seller's items and make them available for sale (refer to Seller Central Help for more details).
Some of your options can include multiple destinations (refer to Seller Central Help for details). Each option can include fees or discounts, which are determined using an algorithm when your shipment is being created, and is not calculated using a set rate. The algorithm for the rebate value and the ship-to location uses multiple factors to optimize your shipments, including expected volume, the availability of carrier appointments, and fulfillment speed. The rebate that your shipment is eligible for is provided during shipment creation.
The terms and conditions can change. Review the current Seller Central terms and conditions, including the Amazon Services Business Solutions Agreement.
Note
When a seller calls
generatePlacementOptions
without inputting box content information, Amazon provides placement options that are optimized for unit-level data (because Amazon does not yet have box data). These options can differ from the placement options that are generated after a seller provides box content information (usingsetPackingInformation
).
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to generatePlacementOptions . |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions
{
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
View the options for shipment splits by calling the listPlacementOptions
operation. This operation provides the list of available placement options, which include:
- A placement option ID
- The option status ("offered" or "accepted")
- Any fees/discounts associated with this option
- The expiration date of the option
- The shipment IDs associated with each option
When a placement option expires, you must regenerate placement options by calling generatePlacementOption
. The placement option ID is required to generate transportation options with generateTransportationOptions
, while shipment IDs are used to understand the contents of each shipment using getShipment
(refer to the following).
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of placement options to return in the response that matches the given query. Minimum : 1 Maximum : 20 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
placementOptions |
Placement options generated for the inbound plan. Type: < PlacementOption > array |
Response example
{
"pagination": {
"nextToken": "string"
},
"placementOptions": [
{
"inboundPlanId": "string",
"placementOptionId": "string",
"status": "OFFERED",
"fees": [
{
"currency": {
"code": "string",
"amount": 0
},
"type": "FEE",
"target": "OUTBOUND_PER_SHIPMENT",
"description": "string"
}
],
"discounts": [
{
"currency": {
"code": "string",
"amount": 0
},
"type": "FEE",
"target": "OUTBOUND_PER_SHIPMENT",
"description": "string"
}
],
"expiration": "2019-08-24T14:15:22Z",
"shipmentIds": [
"string"
]
}
]
}
Review details related to the contents of a shipment within an inbound plan using the getShipment
operation. To call getShipment
, a seller needs to pass the inbound plan ID and shipment ID. A successful response includes placement option ID, shipment confirmed ID (that is, the ID that shows up on labels, created after confirmPlacementOption
), shipment ID (that is, identifier for a shipment prior to the confirmPlacementOption
operation), Amazon reference ID (identifier for scheduling fulfillment center appointments for truck deliveries), selected transportation option ID, name, source, destination FC, ship date, estimated delivery date, status, tracking details, pallet information, contact information, destination region, and FC appointment details.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. | Yes |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}
Response
A successful response includes the following elements:
Name | Description |
---|---|
amazonReferenceId |
A unique identifier created by Amazon that identifies this Amazon-partnered, Less Than Truckload/Full Truckload (LTL/FTL) shipment. Type: string |
contactInformation |
The seller's contact information. Type: ContactInformationWithName |
dates |
Specifies the dates that the seller expects their shipment will be shipped and delivered. Type: Dates |
destination |
The Amazon fulfillment center address and warehouse ID. Type: ShipmentDestination |
selfShipAppointmentDetails |
List of self ship appointment details. Type: < SelfShipAppointmentDetails > array |
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
name |
The name of the shipment. Type: string |
palletInformation |
Pallet information, including weight, dimensions, quantity, stackability, freight class, and declared value. Type: PalletInformation |
placementOptionId |
Identifier to a placement option. A placement option represents the shipment splits and destinations of SKUs. Type: string |
selectedTransportationOptionId |
Identifier to a transportation option. A transportation option represent one option for how to send a shipment. Type: string |
shipmentConfirmationId |
The confirmed shipment ID which shows up on labels (for example, FBA1234ABCD ).Type: string |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. Type: string |
source |
Specifies the 'ship from' address for the shipment. Type: ShipmentSource |
status |
Possible statuses of a shipment. Type: ShipmentStatus |
trackingDetails |
The tracking number of the package, provided by the carrier. For LTL shipments, either freight bill number can be either the freight bill number or the PRO number. Type: TrackingDetails |
Response example
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"shipmentConfirmationId": "string",
"amazonReferenceId": "string",
"selectedTransportationOptionId": "string",
"name": "string",
"source": {
"sourceType": "SELLER_FACILITY",
"address": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
}
},
"destination": {
"destinationType": "AMAZON_OPTIMIZED",
"address": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
},
"warehouseId": "string"
},
"dates": {
"readyToShipWindow": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"editableUntil": "2019-08-24T14:15:22Z"
},
"deliveryWindow": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"editableUntil": "2019-08-24T14:15:22Z"
}
},
"status": "ABANDONED",
"trackingDetails": {
"ltlTrackingDetail": {
"freightBillNumber": [
"string"
],
"billOfLadingNumber": "string"
}
},
"palletInformation": {
"pallets": [
{
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"stackable": true
}
],
"freightClass": "NONE",
"declaredValue": {
"code": "string",
"amount": 0
}
},
"contactInformation": {
"phoneNumber": "string",
"email": "string",
"name": "string"
},
"selfShipAppointmentDetails": [
{
"appointmentId": 0,
"appointmentSlotTime": {
"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"appointmentStatus": "string"
}
]
}
Step 3. Select shipping option
Select shipping options with the confirmPlacementOption
operation. This operation selects the placement option for an inbound plan and creates confirmed shipment IDs for shipments within the inbound plan. The shipmentConfirmationID
is the shipment identifier that appears on labels (for example, FBA1234ABCD
). This ID differs from the initial shipment ID generated by createInboundPlan
. This option cannot be reversed after it is selected. To call confirmPlacementOption
, a seller must pass the inbound plan ID and the selected placement option ID.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
placementOptionId |
Identifier to a placement option. A placement option represents the shipment splits and destinations of SKUs. | Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions/{placementOptionId}/confirmation
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 4. Provide box content information
Note
You need to know which items are associated with each shipment before you call
setPackingInformation
. You can get this information on STA and from the API. If you pass incorrect information, you receive an error message with the expected quantities. You can also retrieve this information for your shipment on Send to Amazon.
Provide information related to what items will be packed into each box by using the setPackingInformation
operation. By calling setPackingInformation
, a seller must pass the following information for boxes they intend to inbound:
- The package grouping ID (that is, the shipment ID of the confirmed placement option) of every shipment
- Box content information source
- Box contents (items, item quantities, prep/label owners for each item)
- Box information (dimensions, weight, and quantity of boxes)
For all ship later packages, you must use BOX_CONTENT_PROVIDED
to specify box dimensions, box weight, and the quantity of each box. A successful response includes the operationId
that can be used to determine the status of the operation using getInboundOperationStatus
.
Tip
In this flow, include
ShipmentId
and omitPackingGroupId
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to setPackingInformation .Type: SetPackingInformationRequest
|
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingInformation
{
"packageGroupings": [
{
"shipmentId": "string",
"boxes": [
{
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"boxId": "string",
"items": [
{
"msku": "string",
"quantity": 1,
"expiration": "string",
"prepOwner": "AMAZON",
"labelOwner": "AMAZON",
"manufacturingLotCode": "string"
}
],
"contentInformationSource": "BOX_CONTENT_PROVIDED"
}
]
}
]
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string",
}
List shipment items
View a paginated list of items in a shipment by calling the listShipmentItems
operation. Sellers must pull this information to understand which items are in each shipment split when they haven't input the carton level information upfront. To call this API, a seller must pass the shipment ID. A successful response contains a paginated list of the products the user previously entered using the createInboundPlan
operation. The response contains the prep instructions for their ASINs, such as prep type and owner. This allows users to conveniently check what items and prep requirements are in a given shipment. The response lists the product’s MSKU, ASIN, FNSKU, Manufacturer Code, quantity, and expiration date if needed. This can be used to generate a pick list which they can use to pull certain items from their inventory and group them into a shipment. The seller then uses the listShipmentBoxes
operation to create a pack list that specifies which items go in which boxes.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment you want to confirm the delivery window option for. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
The number of pallets to return in the response that matches the given query. | No |
paginationToken |
A token to fetch a certain page when there are multiple pages worth of results. The value of this token is fetched from the `pagination` returned in the API response. In the absence of the token value from the query parameter, the API returns the first page of the result. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/items
Response
Name | Description |
---|---|
item |
The items in a shipment. Type: < Item > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "string",
"quantity": 1,
"expiration": "string",
"manufacturingLotCode": "string",
"prepInstructions": [
{
"prepType": "string",
"prepOwner": "string",
"fee": {
"code": "str",
"amount": 0
}
}
]
}
]
}
Step 5. Input transportation data, generate transportation options, and view options
Generate transportation options with the generateTransportationOptions
operation. A transportation option represents the list of available shipping mode and carrier options that are available for each shipment within each placement option. By calling generateTransportationOptions
, a seller must pass the following information:
- Placement option ID
- Shipment ID
- Expected delivery date
- Ship from address, and optionally
- Pallet information. If pallet information is not included, LTL transportation options aren't generated.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to generateTransportationOptions . |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions
{
"body": {
"placementOptionId": "pl1234abcd-1234-abcd-5678-1234abcd5678",
"shipmentTransportationConfigurations": [
{
"contactInformation": {
"email": "[email protected]",
"name": "John Smithy",
"phoneNumber": "1234567890"
},
"freightInformation": {
"declaredValue": {
"amount": 5.5,
"code": "CAD"
},
"freightClass": "FC_50"
},
"pallets": [
{
"dimensions": {
"height": 5,
"length": 3,
"unitOfMeasurement": "CM",
"width": 4
},
"quantity": 2,
"stackability": "STACKABLE",
"weight": {
"unit": "KG",
"value": 5.5
}
}
],
"readyToShipWindow": {
"start": "2024-01-01T00:00Z"
},
"shipmentId": "sh1234abcd-1234-abcd-5678-1234abcd5678"
}
]
}
}
Response
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Review shipment and transportation options by calling the listTransportationOptions
, listDeliveryWindowOptions
, and getShipment
operations.
To call listTransportationOptions
, a seller needs to pass the placement option ID and shipment ID for which they want to view transportation options. A successful response includes all available transportation quotes for all available ship modes and carrier options. Shipping modes include:
- Ground small parcel
- Less-than-truckload freight
- Full truckload freight (palletized)
- Full truckload freight (non-palletized)
- Less than container load ocean
- Full container load ocean
- Air small parcel
- Air small parcel express
Carrier options include Amazon-partnered and non-partnered carriers. Quotes include the cost, a void window (for example, duration where a seller can cancel a shipment and receive a refund for their transportation quote), and expiration for each quote. In regions where fulfillment center appointments are mandatory (for example, India), we provide available appointment slots.
Where our Partnered Carrier Program is available, sellers can take advantage of discounted rates by using an Amazon-partnered carrier for their inbound shipments.
To use an Amazon-partnered carrier for an inbound shipment, select the transportation option where shippingSolution
is AMAZON_PARTNERED_CARRIER
. Note that before using an Amazon-partnered carrier for an inbound shipment, you must read the Seller Central Help about Amazon's Partnered Carrier Program to help ensure that you successfully follow the program instructions and guidelines (Europe) (US). In the EU region, before using an Amazon-partnered carrier for an inbound shipment, you must first review and accept the terms and conditions of the carrier and the terms and conditions of Amazon's Partnered Carrier Program. You can do this on Seller Central. If you attempt to use Amazon Selling Partner APIs to create an inbound shipment using an Amazon-partnered carrier before accepting these terms and conditions, the service returns an error. If a seller is not interested in participating in the Partnered Carrier Program, they are also able to view transportation options that allow them to "choose your own carrier" along with available shipping modes.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of transportation options to return in the response that matches the given query. Minimum : 1 Maximum : 20 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
placementOptionId |
The placement option to get transportation options for. | No |
shipmentId |
The shipment to get transportation options for. Either placementOptionId or shipmentId must be specified. |
No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
transportationOptions |
Transportation options generated for the placement option. Type: < TransportationOption > array |
Response example
{
"pagination": {
"nextToken": "string"
},
"transportationOptions": [
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"transportationOptionId": "string",
"shippingSolution": "string",
"carrier": {
"name": "string",
"alphaCode": "string"
},
"shippingMode": "string",
"quote": {
"cost": {
"code": "str",
"amount": 0
},
"voidableUntil": "2019-08-24T14:15:22Z",
"expiration": "2019-08-24T14:15:22Z"
},
"carrierAppointment": {
"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"programs": [
"string"
]
}
]
}
Review the available delivery window options for each shipment within an inbound plan using the listDeliveryWindowOptions
operation. To make this call, a seller needs to pass the shipmentID
. A successful response provides the startDate
and endDate
for each available delivery window and the level of congestion (availabilityType
) for each option. Note that each option has an expiration date (validUntil
). You must confirm the delivery before this date. If you don't confirm the window by the validUntil
date, you must generate a new window using listDeliveryWindowOptions
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
The number of delivery window options to return in the response that matches the given query. | No |
paginationToken |
A token to fetch a certain page when there are multiple pages worth of results. The value of this token is fetched from the `pagination` returned in the API response. In the absence of the token value from the query parameter, the API returns the first page of the result. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions
Response
A successful response includes the following elements:
Name | Description |
---|---|
deliveryWindowOptions |
Delivery window options generated for the placement option. Type: < DeliveryWindowOption > array |
contactInformation |
Contains tokens to fetch from a certain page. Type: ContactInformation |
Response example
{
"pagination": {
"nextToken": "string"
},
"deliveryWindowOptions": [
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"deliveryWindowOptionId": "string",
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"availabilityType": "string",
"validUntil": "2019-08-24T14:15:22Z"
}
]
}
Review the details related to the contents of a shipment within an inbound plan using the getShipment
operation. To call getShipment
, a seller needs to pass the inbound plan ID and shipment ID. A successful response includes:
- Placement option ID
- Shipment confirmed ID (that is, the ID that shows up on labels)
- Shipment ID (that is, identifier for a shipment prior to the
confirmPlacementOption
operation) - Amazon reference ID (identifier for scheduling fulfillment center appointments for truck deliveries)
- Selected transportation option ID
- Name
- Source
- Destination FC
- Ship date
- Estimated delivery date
- Status
- Tracking details
- Pallet information
- Contact information
- Destination region
- FC appointment details
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. | Yes |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}
Response
A successful response includes the following elements:
Name | Description |
---|---|
amazonReferenceId |
A unique identifier created by Amazon that identifies this Amazon-partnered, Less Than Truckload/Full Truckload (LTL/FTL) shipment. Type: string |
contactInformation |
The seller's contact information. Type: ContactInformationWithName |
dates |
Specifies the dates that the seller expects their shipment will be shipped and delivered. Type: Dates |
destination |
The Amazon fulfillment center address and warehouse ID. Type: ShipmentDestination |
selfShipAppointmentDetails |
List of self ship appointment details. Type: < SelfShipAppointmentDetails > array |
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
name |
The name of the shipment. Type: string |
palletInformation |
Pallet information, including weight, dimensions, quantity, stackability, freight class, and declared value. Type: PalletInformation |
placementOptionId |
Identifier to a placement option. A placement option represents the shipment splits and destinations of SKUs. Type: string |
selectedTransportationOptionId |
Identifier to a transportation option. A transportation option represent one option for how to send a shipment. Type: string |
shipmentConfirmationId |
The confirmed shipment ID which shows up on labels (for example, FBA1234ABCD ).Type: string |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. Type: string |
source |
Specifies the 'ship from' address for the shipment. Type: ShipmentSource |
status |
Possible statuses of a shipment. Type: ShipmentStatus |
trackingDetails |
The tracking number of the package, provided by the carrier. For LTL shipments, either freight bill number can be either the freight bill number or the PRO number. Type: TrackingDetails |
Response example
{
"inboundPlanId": "string",
"placementOptionId": "string",
"shipmentId": "string",
"shipmentConfirmationId": "string",
"amazonReferenceId": "string",
"selectedTransportationOptionId": "string",
"name": "string",
"source": {
"sourceType": "SELLER_FACILITY",
"address": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
}
},
"destination": {
"destinationType": "AMAZON_OPTIMIZED",
"address": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
},
"warehouseId": "string"
},
"dates": {
"readyToShipWindow": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"editableUntil": "2019-08-24T14:15:22Z"
},
"deliveryWindow": {
"start": "2019-08-24T14:15:22Z",
"end": "2019-08-24T14:15:22Z",
"editableUntil": "2019-08-24T14:15:22Z"
}
},
"status": "ABANDONED",
"trackingDetails": {
"ltlTrackingDetail": {
"freightBillNumber": [
"string"
],
"billOfLadingNumber": "string"
}
},
"palletInformation": {
"pallets": [
{
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"stackable": true
}
],
"freightClass": "NONE",
"declaredValue": {
"code": "string",
"amount": 0
}
},
"contactInformation": {
"phoneNumber": "string",
"email": "string",
"name": "string"
},
"selfShipAppointmentDetails": [
{
"appointmentId": 0,
"appointmentSlotTime": {
"startTime": "2019-08-24T14:15:22Z",
"endTime": "2019-08-24T14:15:22Z"
},
"appointmentStatus": "string"
}
]
}
Step 6. Select transportation options
Select transportation options for each shipment within an inbound plan using the confirmTransportationOptions
operation. For Amazon-partnered transportation options, this operation confirms that the seller accepts the Amazon-partnered shipping estimate, agrees to allow Amazon to charge their account for the shipping cost, and requests that the Amazon-partnered carrier ship the inbound shipment. Prior to this call, a seller must have confirmed a placement option for their inbound plan. To call confirmTransportationOptions
, a seller must pass the shipment ID, selected transportation option ID, contact information (needed for partnered carriers for LTL shipments), and estimated delivery date. The estimated delivery date (delivery window) is a requirement for non-partnered carrier options and should not be populated for partnered carrier options. After a transportation option is been confirmed, new transportation options cannot be generated or confirmed for an inbound plan.
Note
If a seller confirms the transportation request, then decides they don't want the Amazon-partnered carrier to ship the inbound shipment, they can use
cancelInboundPlan
to cancel the transportation request. For Small Parcel shipments, the seller has 24 hours after confirming a transportation request to void the request. For Less Than Truckload/Full Truckload (LTL/FTL) shipments, the seller has one hour after confirming a transportation request to void the request. After the relevant time period expires, the seller's account is charged for the shipping cost.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
confirmTransportationOptions request.Type: ConfirmTransportationOptionsRequest |
Yes |
Request example
POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions/confirmation
{
"transportationSelections" : [ {
"contactInformation" : {
"email" : "[email protected]",
"name" : "John Smithy",
"phoneNumber" : "1234567890"
},
"deliveryWindow" : {
"start" : "2024-01-01T00:00Z"
},
"shipmentId" : "sh1234abcd-1234-abcd-5678-1234abcd5678",
"transportationOptionId" : "to1234abcd-1234-abcd-5678-1234abcd5678"
} ]
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Step 7. Printing labels
Call the getLabels
operation to request unique shipping labels for your inbound shipments. Each shipping label returned by the getLabels
operation should be affixed to the package in the shipment that it corresponds to, so the labels indicate the package contents. This helps to ensure that your shipment is processed at the Amazon fulfillment center quickly and accurately.
Refer to Request shipping labels for your inbound shipment for detailed instructions.
Step 8. Send your shipments to Amazon's fulfillment network
Send your shipments to Amazon's fulfillment network using an Amazon-Partnered carrier or a non-Amazon-Partnered carrier that is registered with Amazon. For more information about sending shipments to Amazon's fulfillment network, refer to the Seller Central Help for your marketplace.
As you prepare your shipment, you can retrieve all of the box-level information that you have entered for an inbound plan using the listInboundPlanBoxes
operation.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of packages to return in the response that matches the given query. Minimum : 1 Maximum : 1000 |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/boxes
Response
A successful response includes the following elements:
Name | Description |
---|---|
boxes |
The boxes in an inbound plan. Type: < ListPackagesBox > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"boxes": [
{
"packageId": "string",
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 0,
"boxId": "string",
"templateName": "string",
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "AMAZON",
"quantity": 1,
"expiration": "string",
"manufacturingLotCode": "string",
"prepInstructions": [
{
"prepType": "string",
"prepOwner": "AMAZON",
"fee": {
"code": "string",
"amount": 0
}
}
]
}
],
"shipmentId": "string",
}
]
}
Step 9. Providing tracking information
After sending a shipment to Amazon's fulfillment network using a non-partnered carrier, a seller must share the tracking ID using the updateShipmentTrackingDetails
operation. To call this operation, a seller must pass the shipment ID and tracking details for their less-than-truckload or small parcel shipment. For less-than-truckload shipments, the seller must provide a PRO number (also known as Freight Bill number) and can optionally provide a BOL number. For small parcel shipments, the seller must share an array of box IDs and associated tracking IDs.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
body |
The body of the request to updateShipmentTrackingDetails .Type: UpdateShipmentTrackingDetailsRequest
|
Yes |
Request example
PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/trackingDetails
{
"trackingDetails": {
"ltlTrackingDetail": {
"freightBillNumber": [
"string"
],
"billOfLadingNumber": "string"
}
}
}
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "string"
}
Additional functionality
The Fulfillment Inbound API v2024-03-20 also includes several operations that are not mandatory for every shipment creation. This section describes these operations.
Retrieve a list of existing inbound plans
Retrieve a list of existing inbound plans by using the listInboundPlans
operation. This can be used to retrieve inbound plan information for multiple inbound plans based on criteria that the seller specifies. By calling the listInboundPlans
operation, a seller can filter by state (for example, whether the InboundPlans
are ACTIVE
, SHIPPED
, or VOIDED
) and by either the date that the inbound plan was created or last updated. The seller can also indicate a page size to limit the responses per request and a pagination token if needed.
Important
listInboundPlans
is a paginated call. When you make follow-up calls to get more pages of data, you must pass the same filters as you did in the original call to get the correct response.
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of inbound plans to return in the response that matches the given query. Minimum: 1 Maximum: 30 Type: integer |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. Type: string |
No |
status |
The status of an inbound plan. Type: enum ( Status ) |
No |
sortBy |
Field to sort by creation time. Type: enum ( SortBy ) |
Yes |
sortOrder |
Field to sort ascending or descending. Type: enum ( SortOrder ) |
Yes |
Request example
GET /inbound/fba/2024-03-20/inboundPlans
Response
A successful response includes the following elements:
Name | Description |
---|---|
inboundPlans |
An array of objects that describe selected inbound plans. Type: < InboundPlan > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"inboundPlans": [
{
"inboundPlanId": "string",
"name": "string",
"createdAt": "2019-08-24T14:15:22Z",
"lastUpdatedAt": "2019-08-24T14:15:22Z",
"marketplaceIds": [
"string"
],
"sourceAddress": {
"name": "string",
"companyName": "string",
"addressLine1": "string",
"addressLine2": "string",
"city": "string",
"countryCode": "st",
"stateOrProvinceCode": "string",
"postalCode": "string"
},
"contactInformation": {
"phoneNumber": "string",
"email": "string"
},
"status": "ACTIVE",
"placementOptions": [
{
"placementOptionId": "string",
"status": "OFFERED"
}
],
"shipments": [
{
"shipmentId": "string",
"status": "ABANDONED"
}
],
"packingOptions": [
{
"packingOptionId": "string",
"status": "OFFERED"
}
]
}
]
}
Retrieve a list of items in an inbound plan
Retrieve a list of items within an inbound plan with the listInboundPlanItems
operation. This can be used to retrieve item information for an inbound and can be filtered by package grouping ID (that is, either the ShipmentID
or the PackingGroupId
, depending on whether confirmPlacementOption
has been called). A successful response includes item information such as MSKU, ASIN, FNSKU, label owner, quantity, expiration date, manufacturing lot code, prep instructions, and packing group.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of packages to return in the response that matches the given query. Minimum : 1 Maximum : 1000 Type: integer |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. Type: string |
No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/items
Response
A successful response includes the following elements:
Name | Description |
---|---|
items |
The items in an inbound plan. Type: < ListPackagesItem > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "AMAZON",
"quantity": 1,
"expiration": "string",
"manufacturingLotCode": "string",
"prepInstructions": [
{
"prepType": "string",
"prepOwner": "AMAZON",
"fee": {
"code": "string",
"amount": 0
}
}
],
"shipmentId": "string",
"packingOptionId": "string",
"packingGroupId": "string"
}
]
}
Retrieve a list of pallets associated with inbound plans
Retrieve a list of pallets within an inbound plan with the listInboundPlanPallets
operation. This can be used to retrieve pallet information for an inbound plan and can be filtered by package grouping ID (that is, either the ShipmentID
or the PackingGroupId
, depending on whether confirmPlacementOption
has been called). A successful response includes pallet dimensions, weight, whether the pallets can be stacked, package ID, pallet quantities, and associated shipment IDs.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
Number of packages to return in the response that matches the given query. Minimum : 1 Maximum : 1000 Type: integer |
No |
paginationToken |
When present, pass this string token in the next request to return the next response page. Type: string |
No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/pallets
Response
A successful response includes the following elements:
Name | Description |
---|---|
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
pallets |
The pallets in an inbound plan. Type: < ListPackagesPallet > array |
Response example
{
"pagination": {
"nextToken": "string"
},
"pallets": [
{
"packageId": "string",
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 0,
"stackable": true,
"shipmentId": "string"
}
]
}
Cancel an Inbound Plan
Cancel an inbound plan and all of the associated shipments by using the cancelInboundPlan
operation. This also cancels the fees associated with the transportation options selected by the seller, if this operation is called within the void window. The void window is 24 hours after you confirm a Small Parcel shipment transportation request or one hour after you confirm a Less Than Truckload/Full Truckload (LTL/FTL) shipment transportation request. After this deadline passes, the seller's account is charged for the shipping cost. By calling cancelInboundPlan
, a seller must pass the inboundPlanId
associated with the inbound plan that they intend to cancel. A successful response includes the operationId
that can be used to determine the status of the operation using getInboundOperationStatus
. Alternatively, a seller can confirm that their inbound plan has been voided by retrieving its status by calling getInboundPlan
.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Request example
PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/cancellation
Response
A successful response includes the following elements:
Name | Description |
---|---|
operationId |
UUID for the given operation. Type: string |
Response example
{
"operationId": "operationId1234"
}
Update shipment name
Update the name of a shipment using the updateShipmentName
operation. The user might want to use this to link the shipment ID from the given identifier with a string provided by the user. The shipment ID is preserved after updating this name, and is used to identify the shipment using other operations. To update a shipment name, pass the new name as a string per the request body schema. A successful response gives you an operation ID you can use to check the status of the corresponding operation with getInboundOperationStatus
. The name can be used to find and navigate shipments.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
Identifier to a shipment. A shipment contains the boxes and units being inbounded. Type: string |
Yes |
Body parameterers
Name | Description | Required |
---|---|---|
name |
A human-readable name to update the shipment name to. Type: string |
Yes |
Request example
POST /inbound/fba/version-tbd/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/name
{
"name": "string"
}
Response
updateShipmentName
does not return anything.
Update inbound plan name
Update the name of an existing inbound plan using the updateInboundPlanName
operation. The user might want to use this to link the shipment ID from the given identifier with a string provided by the user. To update an inbound plan name, post the new name as a string per the request body schema. A successful response gives you an operation ID you can use to check the status of the corresponding operation with getInboundOperationStatus
. The name can be used to find and navigate inbound plans.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
Body parameters
Name | Description | Required |
---|---|---|
name |
A human-readable name to update the shipment name to. Type: string |
Yes |
Request example
POST inbound/fba/version-tbd/inboundPlans/{inboundPlanId}/name
{
"name": "string"
}
Response
updateInboundPlanName
does not return anything.
List shipment pallets
View a paginated list of pallets associated with a shipment by calling the listShipmentPallets
operation. An inbound plan contains pallet information after the user has provided the pallet details while generating Less-Than-Truckload (LTL) carrier shipments using the generateTransportationOptions
operation. A successful response contains a paginated list of the previously input pallets and their weights, dimensions, and stackability. The response also contains an identifier for the pallet, which can be used to match a pallet with its labels.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment you want to confirm the delivery window option for. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
The number of pallets to return in the response that matches the given query. | No |
paginationToken |
A token to fetch a certain page when there are multiple pages worth of results. The value of this token is fetched from the `pagination` returned in the API response. In the absence of the token value from the query parameter, the API returns the first page of the result. | No |
Request example
GET inboundPlans/{inboundPlanId}/shipments/{shipmentId}/pallets
Response
Name | Description |
---|---|
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
pallets |
The pallets in a shipment. Type: < Pallet > array |
Response example
{
"pagination": {
"nextToken": "string"
},
"pallets": [
{
"packageId": "string",
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"stackability": "STACKABLE"
}
]
}
List shipment boxes
View a paginated list of box packages in a shipment by calling the listShipmentBoxes
operation. Shipping boxes must first be generated with the setPackingInformation
operation before becoming available. To call listShipmentBoxes
, a seller must pass the shipment ID. A successful response includes information about the boxes in the shipment and the items in the boxes. Each box has a corresponding package ID which can be used to match box labels to boxes. The response also includes details about each box such as its weight / dimensions and what items are inside each box. The response includes the following for each item:
- MSKU
- ASIN
- FNSKU
- Manufacturer lot code
- Label owner
- Prep instruction
- Prep type
- Prep owner
If the items have expiration dates, those are included in the response. This API gives a detailed list of information that users need to create a pack list that can be used to help ensure the shipment is complete before sending to the fulfillment centers.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment you want to confirm the delivery window option for. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
The number of pallets to return in the response that matches the given query. | No |
paginationToken |
A token to fetch a certain page when there are multiple pages worth of results. The value of this token is fetched from the `pagination` returned in the API response. In the absence of the token value from the query parameter, the API returns the first page of the result. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/boxes
Response
Name | Description |
---|---|
boxes |
A list of boxes in a shipment. Type: < Box > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"boxes": [
{
"packageId": "string",
"weight": {
"unit": "LB",
"value": 0
},
"dimensions": {
"unitOfMeasurement": "IN",
"length": 0,
"width": 0,
"height": 0
},
"quantity": 1,
"boxId": "string",
"templateName": "string",
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "string",
"quantity": 1,
"expiration": "string",
"manufacturingLotCode": "string",
"prepInstructions": [
{
"prepType": "string",
"prepOwner": "string",
"fee": {
"code": "str",
"amount": 0
}
}
]
}
],
"destinationRegion": {
"countryCode": "string",
"state": "string",
"warehouseId": "string"
}
}
]
}
Create marketplace item labels
The createMarketplaceItemLabels
operation provides labels for a list of MSKUs for a given marketplace. Using this operation you can get item labels in the marketplace language. This is useful for dynamic sellers who operate in multiple marketplaces, and allows you to easily identify which items are planned for which markets.
Body parameters
Name | Description | Required |
---|---|---|
height |
The height of the item label. | No |
labelType |
Indicates the print type for a given label. | Yes |
localeCode |
The locale code constructed from ISO 639 language code and ISO 3166-1 alpha-2 standard of country codes separated by an underscore character. | No |
marketplaceId |
The Marketplace ID. Refer to Marketplace IDs for a list of possible values. | Yes |
mskuQuantities |
Represents the quantity of an msku to print item labels for. | Yes |
pageType |
The page type to use to print the labels. **Possible values:** `A4_21`, `A4_24`, `A4_24_64x33`, `A4_24_66x35`, `A4_24_70x36`, `A4_24_70x37`, `A4_24i`, `A4_27`, `A4_40_52x29`, `A4_44_48x25`, `Letter_30`. | No |
width |
The width of the item label. | No |
Request example
GET /inbound/fba/2024-03-20/marketplaces/{marketplaceId}/itemLabel
Response
Name | Description |
---|---|
documentDownloads |
Resources to download the requested document. |
Response example
{
"documentDownloads": [
{
"uri": "string",
"downloadType": "string",
"expiration": "2019-08-24T14:15:22Z"
}
]
}
List shipment items
View a paginated list of items in a shipment by calling the listShipmentItems
operation. Sellers need this information to learn which items are in each shipment split if they didn't input the carton-level information.
To call this operation, a seller must pass the shipment ID.
A successful response contains a paginated list of the products the user previously entered using the createInboundPlan
operation. The response contains the prep instructions for their ASINs, such as prep type and owner. This allows users to conveniently check what items and prep requirements are in a given shipment. The response also lists the product’s MSKU, ASIN, FNSKU, Manufacturer Code, quantity, and expiration date if needed. This can be used to generate a pick list that they can use to pull certain items from their inventory and group them into a shipment. The seller then uses the listShipmentBoxes
operation to create a pack list of which items go in which boxes.
Path parameters
Name | Description | Required |
---|---|---|
inboundPlanId |
The inboundPlanId identifies an inbound plan.Type: string |
Yes |
shipmentId |
The shipment you want to confirm the delivery window option for. | Yes |
Query parameters
Name | Description | Required |
---|---|---|
pageSize |
The number of pallets to return in the response that matches the given query. | No |
paginationToken |
A token to fetch a certain page when there are multiple pages worth of results. The value of this token is fetched from the `pagination` returned in the API response. In the absence of the token value from the query parameter, the API returns the first page of the result. | No |
Request example
GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/items
Response
Name | Description |
---|---|
item |
The items in a shipment. Type: < Item > array |
pagination |
Contains tokens to fetch from a certain page. Type: Pagination |
Response example
{
"pagination": {
"nextToken": "string"
},
"items": [
{
"msku": "string",
"asin": "string",
"fnsku": "string",
"labelOwner": "string",
"quantity": 1,
"expiration": "string",
"manufacturingLotCode": "string",
"prepInstructions": [
{
"prepType": "string",
"prepOwner": "string",
"fee": {
"code": "str",
"amount": 0
}
}
]
}
]
}
Prerequisite step. Create a listing and convert it to FBA
If a product already exists in the Amazon catalog, creating a listing can be as simple as associating a unique seller-defined SKU with the unique Amazon-defined ASIN (Amazon Standard Item Number) for the product. If a product does not yet exist in the Amazon catalog, creating a listing requires providing descriptive information about the product so Amazon can build a record and assign an ASIN to the product. You can create listings by submitting feeds using the Feeds API section.
Refer to Create a listing and convert it to FBA for detailed instructions.
Updated 3 days ago