Migrating Fulfillment Inbound workflows
Migrate your existing Fulfillment Inbound API workflows from v0 to v2024-03-20.
This guide describes how to migrate from the Fulfillment Inbound API v0 (“v0”) to the Fulfillment Inbound API v2024-03-20 (“v2024-03-20”). It follows the v0 workflow and describes how to accomplish the same tasks with v2024-03-20. This migration is necessary, as certain operations in v0 are deprecated.
Important!
Review the new Fulfillment Inbound shipment workflow before you go through this migration guide.
Create an inbound shipment plan
To create an inbound shipment plan, the seller provides key information to Amazon about the items, such as:
- Ship-from address
- Items summary
- Label and prep preference
Amazon uses this information to create a shipment plan for your items, so the items can be appropriately packed and sent to an Amazon fulfillment center.
The v0 operation createInboundShipmentPlan
is replaced with a set of operations in v2024-03-20. These new operations provide sellers with several packing and placement options, similar to the Send To Amazon workflow in Seller Central:
v0 operation | v2024-03-20 operations | Functionality |
---|---|---|
createInboundShipmentPlan |
createInboundPlan |
Create an inbound plan. |
generatePackingOptions |
Determine which SKUs can be packed together. | |
listPackingOptions |
||
listPackingGroupItems |
||
confirmPackingOption |
||
setPackingInformation |
Provide box content information. | |
generatePlacementOptions |
Generate and view options for destination fulfillment centers. | |
listPlacementOptions |
Review shipment splits. | |
getShipment |
Request and response mapping
When you make requests and interpret responses with the new operations, consider the following:
destinationMarketplaces
is replaced withshipToCountryCode
andShipToCountrySubdivisionCode
in requests.- Label and prep preference is replaced with Label and prep owners.
PrepDetailList
is not available as an input. The seller must enter the prep category in Seller Central in advance for each SKU. This is a one-time activity per SKU and the prep category persists.- You retrieve fees and discounts from the
listPackingOptions
response for the packing option, and from thelistPlacementOptions
response for different placement options. createInboundPlan
generates shipment IDs. These are different fromshipmentConfirmationIDs
, which are the identifiers that appear on labels (for example,FBA1234ABCD
).getShipment
retrieves both of these IDs, along with the Amazon reference ID, after confirming placement in the next step.- The v0 operation
createInboundShipmentPlan
returns theDestinationFulfillmentCenterId
. In v2024-03-20,getShipment
returns this at the shipment ID level. - The v0 operation
createInboundShipmentPlan
returns theEstimatedBoxContentsFee
. Use the v0 operationgetShipments
to retrieve this. For more details, refer to the Preserved workflows section.
Version 0 features
When you call createInboundShipmentPlan
with an address and required shipping information, it returns a list of inbound plans, each containing a shipment ID, destination FC, items, and fees.
Version 2024-03-20 features
You create inbound shipment plans in a highly customizable way in the new version:
Task | Operation |
---|---|
Create an inbound plan with an address, marketplace, and items summary. | createInboundPlan |
Determine which SKUs can be packed together. The seller has the ability to generate packing options in this step. Each PackingOption includes a set of PackingGroups , each of which contains a set of SKUs that can be packed together. Information such as fees, discounts, shipping modes, and expiration date can help the seller choose between options. | generatePackingOptions listPackingOptions confirmPackingOption |
Provide information related to the items that are packed into each box, including items, item quantities, dimensions, weight, and quantity of boxes. | setPackingInformation |
Generate placement options (shipment splits) that are available for the inbound plan. Each placement option describes the destination FCs and shipping options for each item in the inbound plan. Each option can include fees or discounts. | generatePlacementOptions |
Get the list of available placement options, which includes a placement option ID, status (offered or accepted), any fees and discounts, the expiration date, and the shipment IDs associated with each option. | listPlacementOptions |
Review details related to the content of each shipment referenced by the shipment ID. | getShipment |
Note
All POST operations in the new flow are asynchronous and must be followed by
getInboundOperationStatus
to retrieve their status.
Create an inbound shipment
An inbound shipment indicates to Amazon that a shipment of items will arrive at a particular Amazon fulfillment center soon.
In v0, you use createInboundShipment
for this task. In v2024-03-20, you use confirmPlacementOption
.
v0 operation | v2024-03-20 operation | Functionality |
---|---|---|
createInboundShipment | confirmPlacementOption | Select shipping option. |
Request and response mapping
When you make requests and interpret responses with the new operations, consider the following:
- In v0,
InboundShipmentHeader
andInboundShipmentItems
must be passed for each shipment ID in the request. In v2024-03-20, onlyinboundPlanId
andplacementOptionId
are required. shipmentID
in v0 is replaced withshipmentConfirmationID
in v2024-03-20 and is generated when you create an inbound shipment.
Version 0 features
To create an inbound shipment, send an inbound shipment header with shipment items and a marketplace ID for each shipment ID.
Version 2024-03-20 features
The confirmPlacementOption
operation confirms the placement option for an inbound plan, selects the placement splits for an inbound plan, and creates confirmed shipment IDs for all shipments within the inbound plan. The shipmentConfirmationID
generated in this step is the shipment identifier that appears on labels (for example, FBA1234ABCD
).
Note that this step is performed after generating transportation options only when carton content is known in advance. For the correct order of operations to create a shipment plan using the new APIs, refer to Creating a shipment when the seller knows the carton-level information up-front
Submit carton content information
The POST_FBA_INBOUND_CARTON_CONTENTS
feed in v0 is replaced with setPackingInformation
.
v0 | v2024-03-20 operation | Functionality |
---|---|---|
POST_FBA_INBOUND_CARTON_CONTENTS feed | setPackingInformation | Provide box content information. |
Request and response mapping
The POST_FBA_INBOUND_CARTON_CONTENTS
feed contains all information about the cartons in XSD format for the shipment ID level. setPackingInformation
requires the same information at either the Packing group level or Shipment ID level. Box weight and dimensions are new.
Version 0 features
The Feeds API is a separate API for bulk updates. The feeds input must conform to the XSD
format.
Version 2024-03-20 features
setPackingInformation
simplifies the submission of carton content information.- You can provide packing information at two stages depending on whether carton level information is known at the time of packing:
- If packing information is known, call
setPackingInformation
with the packing group ID before placement confirmation. - If packing information is unknown, call
setPackingInformation
with the shipment ID after placement confirmation.
- If packing information is known, call
For an outline of the two workflows, refer to Fulfillment Inbound shipment workflow.
Submit transportation information and estimate shipping cost
When you submit transportation information and get an estimate of shipping costs for Amazon-partnered carriers, you also provide information that Amazon fulfillment centers can use to plan for the arrival of your shipment.
v0 operations | v2024-03-20 operations | Functionality |
---|---|---|
putTransportDetails |
generateTransportationOptions generateDeliveryWindowOptions
|
Input transportation data, generate transportation options, generate delivery windows, and view transportation and delivery window options. |
estimateTransport |
||
getTransportDetails |
listTransportationOptions listDeliveryWindowOptions
|
Request and response mapping
When you make requests and interpret responses with the new operations, consider the following:
- The v0 operation
putTransportDetails
requires shipment type (small parcel or a Less Than Truckload/Full Truckload [LTL/FTL]) whether using a partnered carrier or not. It requires transport details for parcel or LTL data if using an Amazon partnered carrier. Few details, such as name and tracking details, are required for non-partnered carriers. In v2024-03-20,generateTransportationOptions
requires ship from address, ready to ship date, and pallet information (if applicable) to generate estimates. - The v0 operations
estimateTransport
andgetTransportDetails
useshipmentID
as the identifier. In v2024-03-20,listTransportationOptions
requires a placement option ID and shipment ID. - In v0, the
PartneredEstimate
response element contains the estimate. In v2024-03-20, the list response includes all available transportation quotes for all available ship modes and carrier options.
Version 0 features
- Estimates are generated based on the shipment type and carrier details provided by the seller. This is applicable only to partnered carriers.
- v0 uses
putTransportDetails
to request estimates, followed byestimateTransport
andgetTransportDetails
. The estimate is returned in thePartneredEstimate
response element.
Version 2024-03-20 features
- Amazon generates a list of transportation options. This list contains all available shipping modes and carrier options for each shipment within each placement option based on delivery date and address.
- Carrier options include Amazon-partnered and non-partnered carriers. Each quote includes the cost, a void window, and an expiration date. The void window is the time period in which a seller can cancel a shipment and receive a refund for their transportation quote. If pallet information is not included, LTL transportation options are not generated.
- Generate transportation options with
generateTransportationOptions
, then list transportation options with estimated costs usinglistTransportationOptions
. - To generate delivery window options separately, use
generateDeliveryWindowOptions
. Delivery windows are seven-day periods during which a seller can deliver their shipment to the destination 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. This is a new feature in v2024-03-20. - Call
generateDeliveryWindowOptions
to generate delivery window options, followed bylistDeliveryWindowOptions
to review available delivery window options for each shipment within an inbound plan. Note that each option has an expiration date (validUntil
). The delivery must be confirmed before this date.
Confirm the transportation request
When a seller confirms a transportation request for an Amazon-partnered transportation option, they also confirm that they:
- Accept the Amazon-partnered shipping estimate
- Agree to allow Amazon to charge their account for the shipping cost
- Request that the Amazon-partnered carrier ship the inbound shipment
v0 operation | v2024-03-20 operations | Functionality |
---|---|---|
confirmTransport | confirmDeliveryWindowOptions confirmTransportationOptions | Select transportation options. |
Request and response mapping
When you make requests and interpret responses with the new operations, consider the following:
- In v0,
confirmTransport
requires only theshipmentID
. In v2024-03-20,confirmDeliveryWindowOptions
requiresshipmentID
and a selected delivery window option ID. To callconfirmTransportationOptions
, the seller must pass the shipment ID, selected transportation option ID, contact information (needed for partnered carriers for LTL shipments), and estimated delivery date (needed for non-partnered carriers). - v0 returns
TransportStatus
, which provides the status of the Amazon-partnered carrier shipment.
Version 0 features
confirmTransport
confirms the transportation request at the shipmentID
level.
Version 2024-03-20 features
- Choose delivery windows for each shipment within a plan using
confirmDeliveryWindowOptions
. All transportation options that have the programDELIVERY_WINDOW_REQUIRED
require you to confirm a delivery window before you confirm a transportation option. This is a new requirement in v2024-03-20. - The way you select transportation options for each shipment within an inbound plan using the
confirmTransportationOptions
operation is similar to v0. You must confirm a transportation option before printing labels, even for non Amazon-partnered transportation.
Send shipment tracking numbers to Amazon
To share tracking details with Amazon after sending a shipment to Amazon's fulfillment network using a non-partnered carrier, use updateShipmentTrackingDetails
.
v0 operation | v2024-03-20 operation | Functionality |
---|---|---|
putTransportDetails | updateShipmentTrackingDetails | Provide tracking information. |
Request and response mapping
In v0, putTransportDetails
requires shipment tracking numbers using TrackingId
(small parcel) and PRO number (LTL). In v2024-03-20, updateShipmentTrackingDetails
requires shipment ID and tracking details for LTL or small parcel shipments.
Version 0 features
Tracking details are embedded in the putTransportDetails
operation.
Version 2024-03-20 features
putTransportDetails
is a dedicated operation for updating tracking details. For LTL shipments, the seller must provide a PRO number (also known as Freight Bill number) and can optionally provide a Bill of Lading (BOL) number. For small parcel shipments, the seller must share an array of box IDs and associated tracking IDs.
Mark your shipments as shipped
You do not need to mark your shipments as shipped in v2024-03-20. Amazon automatically tracks the shipments based on the carrier and tracking details.
Cancel a transportation request
To cancel a transportation request, use cancelInboundPlan
.
v0 operation | v2024-03-20 operation | Functionality |
---|---|---|
voidTransport | cancelInboundPlan | Cancel an inbound plan. |
Request and response mapping
In v0, you cancel transportation requests at the shipment ID level. In v2024-03-20, you do it at the inbound plan level.
Version 0 features
v0 uses voidTransport
to cancel the transportation request. After you confirm a transportation request, you have 24 hours to void it for a small parcel shipment, and one hour to void it for an LTL/FTL shipment.
Version 2024-03-20 features
cancelInboundPlan
also cancels the fees associated with the transportation options selected by the seller if it's 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 an LTL/FTL shipment transportation request. This is the same as in v0.
Preserved workflows
The following v0 operations are not deprecated:
Operations | Functionality |
---|---|
getLabels |
Print box label, pallet label, or bill of lading. |
getBillOfLading |
|
getShipmentItemsByShipmentId |
Get quantity shipped and quantity received. |
getShipmentItems |
|
getShipments |
Get shipment status. |
getPrepInstructions |
Get item preparation instructions. |
Important!
Use
shipmentConfirmationID
in place ofshipmentId
for all v0 operations that are not deprecated. There is a known issue where single SKU details are not shown in the box labels in the new version.
Create a listing and convert it to FBA remains a prerequisite step for using the new version.
Updated about 1 month ago