Amazon Selling Partner API documentation specifies that the Fulfillment Inbound API v2024-03-20 fundamentally restructures how merchants and warehouse management systems transmit inventory into Amazon fulfillment centers [1] [2]. In contrast to the legacy v0 API where destination fulfillment centers were returned immediately upon plan creation, the v2024-03-20 architecture separates inbound logistics into distinct generative stages: Inbound Plans, Packing Options, Placement Options, Transportation Options, and Delivery Windows [1] [3]. Every generative transition executes asynchronously via getInboundOperationStatus polling [3]. Shipments remain in UNCONFIRMED status until a merchant confirms a specific placement option, locking fulfillment splits and placement fees [3]. Understanding this multi-stage lifecycle is required to prevent warehouse dispatch stalls, fee surprises, and synchronization failures between physical warehouse management systems and Amazon Fulfillment by Amazon (FBA) networks.
1. The Inbound Plan Lifecycle: Deconstructing the v2024-03-20 Architecture
For merchants sending inventory to Fulfillment by Amazon (FBA), the legacy v0 Fulfillment Inbound API treated shipment planning as a synchronous, single-phase operation. A merchant submitted item lists to createInboundShipmentPlan, received immediate destination fulfillment center allocations, generated shipments with createInboundShipment, and subsequently transmitted carton contents. This architecture failed to reflect physical logistics realities, where box packing often occurs before destination centers are known, and where regional placement fee trade-offs dictate optimal routing.
Amazon Selling Partner API documentation specifies that version v2024-03-20 decouples shipment planning into an immutable plan container with staged generative options [1] [2]. An inbound plan begins with createInboundPlan, which accepts the source address, destination marketplace identifiers, and item manifests [3]. Rather than dictating final destinations upfront, Amazon generates packing configurations and placement options that allow sellers to evaluate operational costs and shipment splits prior to committing inventory [1] [3].
Accessing the Fulfillment Inbound API v2024-03-20 requires the Amazon Fulfillment role authorized on the developer profile [1] [4]. Documented platform support covers all Amazon regional stores except Brazil [1]. Furthermore, Amazon documentation explicitly notes that several legacy v0 operations remain active and are not deprecated, including getLabels, getBillOfLading, getPrepInstructions, getShipments, getShipmentItemsByShipmentId, and getShipmentItems [1]. Of these, getLabels and getBillOfLading remain necessary operational components to generate physical box and pallet shipping documentation [1].
2. The Six-Stage Generative Pipeline and Asynchronous Polling
The v2024-03-20 inbound workflow operates across six sequential stages. Each generative step initiates a background calculation within Amazon logistics systems and returns an operationId rather than immediate resource payloads [1] [3].
| Workflow Stage | Primary API Operations | Input Parameters | Documented Output |
|---|---|---|---|
| 1. Plan Initialization | createInboundPlan | Source address, marketplace IDs, item MSKUs, prep ownership | inboundPlanId, operation status, initial plan metadata |
| 2. Packing Resolution | generatePackingOptions, setPackingInformation | Plan ID, optional box packaging details, item associations | packingOptionId, pack groups, supported configurations |
| 3. Placement Selection | generatePlacementOptions, confirmPlacementOption | Plan ID, confirmed packing option ID, placement option ID | placementOptionId, shipment IDs, placement fees and discounts |
| 4. Transportation Quote | generateTransportationOptions, confirmTransportationOptions | Shipment ID, shipping mode (SPD/LTL), carrier selection | transportationOptionId, carrier quotes, appointment details |
| 5. Delivery Window | generateDeliveryWindowOptions, confirmDeliveryWindowOptions | Shipment ID, freight availability dates, window option ID | deliveryWindowOptionId, scheduled arrival timeframes |
| 6. Label Generation | createMarketplaceItemLabels, legacy getLabels | Shipment ID, carton counts, label format preferences | Thermal or PDF carton barcodes, pallet placards, bills of lading |
Because generative operations require backend logistics routing, the API returns an operationId with status IN_PROGRESS [3]. Warehouse integrations cannot proceed synchronously. The calling client must poll getInboundOperationStatus until operationStatus returns SUCCESS [3]. If operationStatus returns FAILED, the operationProblems array provides structured error codes explaining whether item compliance, address validity, or dimensional constraints caused the failure [3].
3. Packing Options: Amazon-Recommended vs Custom Carton Configurations
Amazon defines pack groups as sets of SKUs that can be physically packed together without violating prep or hazardous material separation requirements [1] [3]. SKUs that cannot share a carton are segmented into separate pack groups, each requiring independent packing and carton labeling [1].
The documentation specifies two primary operational pathways for carton configuration [1]:
- Amazon-Recommended Packing: Sellers receive automated pack group suggestions that qualify for fulfillment fee discounts [1]. This pathway is restricted to small parcel delivery (SPD) where each individual carton weighs less than 15 kg [1]. It is currently available in five European Amazon stores: the United Kingdom, Germany, France, Italy, and Spain [1]. If selected with partnered carriers, the destination fulfillment center may be assigned as
AMAZON_OPTIMIZED, where final routing addresses appear exclusively on printed carton labels [1]. - Custom Carton Configurations: For merchants operating standard warehouse packaging lines where carton contents are determined prior to plan creation, the system accepts explicit box dimensions, gross weights, and item-to-box mappings via
setPackingInformationusing theBoxInputschema [1] [3]. - Pack Later Option: Enables merchants to defer box-level content submissions during initial planning [1]. Amazon documentation specifies that this option is available exclusively for palletized less-than-truckload (LTL) shipments [1].
Prior to submitting box content manifests, integrators must determine prep and labeling responsibility. Amazon provides the listPrepDetails operation to inspect whether prepOwner and labelOwner must be designated as SELLER, AMAZON, or NONE [5]. If allOwnersConstraint returns MUST_MATCH, the prep owner and label owner values passed to createInboundPlan must be identical [5].
4. Placement Options, Inbound Splits, and Fee Mechanics
Once packing options are resolved and confirmed, the merchant generates placement options using generatePlacementOptions [1] [3]. In the v2024-03-20 model, placement options represent the geographic distribution strategy that Amazon assigns to the inbound plan [3].
Each placement option in the listPlacementOptions response contains distinct financial and structural attributes [3]:
- Placement Option ID: The unique identifier passed to
confirmPlacementOptionto lock the selected routing strategy [3]. - Shipment ID Array: The specific shipment containers generated under this placement option [3]. A single inbound plan may be split into one, two, three, or more regional shipments depending on inventory distribution needs [1] [3].
- Fees and Discounts: The exact placement service fees or inbound defect discounts associated with the option [1] [3]. Options that require Amazon to distribute inventory across its internal network incur higher placement fees, whereas options where the merchant splits shipments across multiple regional facilities receive lower fees or incentives [1] [3].
- Expiration Timestamp: Each placement option carries an ISO 8601 expiration date [3]. If a merchant fails to confirm an option before expiration, its status transitions from
OFFEREDtoEXPIRED, requiring a new call togeneratePlacementOptions[3].
Calling confirmPlacementOption is the decisive state boundary in the inbound lifecycle [1] [3]. Once confirmed, the placement option status transitions to ACCEPTED, the inbound plan locks its shipment splits, and each child shipment transitions from UNCONFIRMED to WORKING status [3].
5. Shipment State Machine and Mid-Flight Modification Boundaries
Child shipments created within an inbound plan follow an explicit state machine defined in the Shipment schema [3]. Tracking these transitions allows warehouse management systems to synchronize internal purchase orders and inventory ledgers with physical freight progress.
| Shipment Status | Lifecycle Definition | Permitted Operations and Triggers |
|---|---|---|
UNCONFIRMED | Initial shipment state created during placement generation | Read-only visibility; cannot be dispatched or labeled until placement is confirmed [3] |
WORKING | Active operational shipment with confirmed placement allocation | Transportation options can be quoted; box labels and manifests can be finalized [3] |
READY_TO_SHIP | Carton labels and transportation options confirmed | Freight ready for carrier handover or dock pickup [3] |
SHIPPED | Carrier has picked up freight and tracking details are recorded | Tracking details updated via updateShipmentTrackingDetails [1] [3] |
IN_TRANSIT | Freight is moving across regional carrier networks | Carrier scans update transit milestones [3] |
DELIVERED | Shipment has arrived at the destination fulfillment center dock | Amazon dock scan logs trailer arrival [3] |
CHECKED_IN | Trailer or container unsealed and receiving dock queue initiated | Fulfillment center staging underway [3] |
RECEIVING | Cartons opened, individual units scanned, and items verified | Salable inventory appears in Amazon FBA available inventory [3] |
CLOSED | Receiving complete or discrepancy reconciliation window finalized | Final received quantities locked for accounting reconciliation [3] |
A frequent operational hazard in warehouse operations is handling packing adjustments after an inbound plan has been generated. Amazon documentation defines strict boundaries for updating shipment contents [5]:
- Quantity Modification Ceilings: Merchants can adjust unit quantities using
generateShipmentContentUpdatePreviews, but adjustments are permitted only before the shipment entersRECEIVINGstatus [5]. Quantity changes are strictly limited to at most 5% or 6 units per SKU per shipment, whichever is greater [5]. - SKU Removal Constraints: An existing SKU can be removed from a shipment only if its original planned quantity was 6 units or fewer per shipment [5]. Merchants cannot remove all SKUs or leave a shipment empty [5].
- Cancellation Void Windows: When an inbound plan must be discarded entirely,
cancelInboundPlancancels the plan and voids associated partnered carrier transportation fees [5]. However, fee voiding is strictly bounded: the void window is 24 hours after confirming transportation for Small Parcel shipments, and only 1 hour for palletized freight [5].
6. A Resilient ERP and WMS Integration Protocol
To prevent stockouts, unauthorized fee commitments, and warehouse dock gridlock when integrating ERP or WMS systems (such as NetSuite, SAP, or Cin7) with the v2024-03-20 API, SANOCEA recommends establishing an event-driven integration architecture structured around five operational principles.
Execute box packing, barcode scanning, and weight verification on the warehouse floor prior to generating placement options. Submitting exact carton weights and FNSKU contents via custom packing information prevents costly split revisions.
Wrap every generative endpoint (generatePackingOptions, generatePlacementOptions, generateTransportationOptions) in an isolated task queue that polls getInboundOperationStatus at escalating intervals (2s, 4s, 8s, 16s) to avoid rate limit throttling while awaiting Amazon routing calculations.
Parse the fee and discount arrays in listPlacementOptions automatically. If Amazon proposes an unexpected regional split or a placement fee exceeding configured gross margin thresholds, quarantine the plan for merchant approval before calling confirmPlacementOption.
Store the immutable JSON payload of listShipmentBoxes and listShipmentItems alongside warehouse picking records. If freight arrives with receiving discrepancies, the stored manifest provides primary evidence for reimbursement disputes.
If pallet freight is damaged on the dock or staging errors occur, trigger cancelInboundPlan within the documented 1-hour window to avoid non-refundable freight carrier charges.
7. Cutover Verification Checklist for Engineering Teams
Before deprecating legacy v0 inbound scripts and routing live warehouse orders through the v2024-03-20 pipeline, engineering teams must verify the following documented technical preconditions:
- Verify that the SP-API application registration includes the
Amazon Fulfillmentrole in Seller Central [1] [4]. - Confirm that legacy
v0label retrieval endpoints (getLabels,getBillOfLading) are preserved in your integration codebase, as Amazon maintains them for printing box and pallet shipping documents [1]. - Validate that prep and labeling constraints are queried via
listPrepDetailsduring catalog synchronization so thatprepOwnerandlabelOwnerconstraints (AMAZON,SELLER,NONE) are populated accurately during plan creation [5]. - Verify that warehouse pack stations enforce the 15 kg threshold if your operations utilize Amazon-recommended packing for European fulfillment centers [1].
- Ensure that automated shipment update routines respect the documented 5% or 6-unit ceiling and that any discrepancy exceeding this threshold triggers a clean plan cancellation rather than a rejected content update [5].
- Confirm that delivery window generation (
generateDeliveryWindowOptions) is integrated into carrier scheduling pipelines for all non-partnered LTL and FTL freight [1] [3].
Sources
- Amazon Selling Partner API: Fulfillment Inbound API v2024-03-20 documentation (retrieved 2026-10-15)
- Amazon Selling Partner API: Fulfillment Inbound v2024-03-20 API reference (retrieved 2026-10-15)
- Amazon Selling Partner API: Fulfillment Inbound API v2024-03-20 OpenAPI model (retrieved 2026-10-15)
- Amazon Selling Partner API: Roles in the Selling Partner API (retrieved 2026-10-15)
- Amazon Selling Partner API: Additional functionality in Fulfillment Inbound v2024-03-20 (retrieved 2026-10-15)