Migrating Fulfillment Inbound workflows

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:

Request and response mapping

When you make requests and interpret responses with the new operations, consider the following:

• destinationMarketplaces is replaced with shipToCountryCode and ShipToCountrySubdivisionCode 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 the listPlacementOptions response for different placement options.
• createInboundPlan generates shipment IDs. These are different from shipmentConfirmationIDs, 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 the DestinationFulfillmentCenterId. In v2024-03-20, getShipment returns this at the shipment ID level.
• The v0 operation createInboundShipmentPlan returns the EstimatedBoxContentsFee. Use the v0 operation getShipments 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:

📘

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.

Request and response mapping

When you make requests and interpret responses with the new operations, consider the following:

• In v0, InboundShipmentHeader and InboundShipmentItems must be passed for each shipment ID in the request. In v2024-03-20, only inboundPlanId and placementOptionId are required.
• shipmentID in v0 is replaced with shipmentConfirmationID 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.

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.

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.

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 and getTransportDetails use shipmentID 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 by estimateTransport and getTransportDetails. The estimate is returned in the PartneredEstimate 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 using listTransportationOptions.
• 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 by listDeliveryWindowOptions 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

Request and response mapping

When you make requests and interpret responses with the new operations, consider the following:

• In v0, confirmTransport requires only the shipmentID. In v2024-03-20, confirmDeliveryWindowOptions requires shipmentID and a selected delivery window option ID. To call confirmTransportationOptions, 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 program DELIVERY_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.

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.

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:

🚧

Important!

Use shipmentConfirmationID in place of shipmentId 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.