selling-partner-fba-inbound-management

Overview

Guides a Fulfillment by Amazon (FBA) seller through sending inventory to Amazon's fulfillment network end to end. It runs the sequential inbound pipeline (create the plan, set packing, choose placement, book transportation, confirm a delivery window, confirm the shipment), polls each asynchronous operation to a confirmed result before advancing, and pauses at every decision gate for the seller's choice. It also handles status checks, tracking, labels, prep, and modify or cancel. It is the shipment-execution member of the Selling Partner API (SP-API) seller family, and is where selling-partner-stockout-prevention routes a seller who needs to create or expedite a shipment. It is not autonomous: nothing irreversible or fee-charging happens without an explicit, restated confirmation.

Workflow

<Definition - Inbound Plan> The top-level container for sending inventory to Amazon: one plan holds the items, the boxes, the resulting shipments, and the chosen placement and transportation. It is created first (createInboundPlan) and identified by an inboundPlanId that every later stage references. Only plans created with the current inbound flow are visible to these operations; shipments created in Seller Central or an older flow are not. </Definition - Inbound Plan>

<Definition - Async Operation> Almost every write returns an operationId rather than a finished result, because Amazon processes it in the background. The operation is not done until its status reads SUCCESS. FAILED means it did not apply and the error must be read. IN_PROGRESS means still processing: wait and poll again, bounded per Rule 3. Treat an operationId as a receipt to check, never as confirmation the change took effect. </Definition - Async Operation>

<Definition - Generate-List-Confirm> The three-call pattern each pipeline stage follows. Generate asks Amazon to compute the options (an async operation), list reads back the computed options, and confirm commits the seller's chosen option. Placement and transportation add a cost to this: their confirm is permanent and charges money, so it sits behind the hard gate in Rule 4. </Definition - Generate-List-Confirm>

<Definition - Placement Option> One way Amazon proposes to split the shipment across fulfillment centers, each with its own set of destination centers and its own placement fee in dollars. Confirming a placement option (confirmPlacementOption) is permanent for the plan and charges that fee. There is no preview or undo, which is why it is a hard-gated action. </Definition - Placement Option>

<Definition - Partnered vs Non-Partnered Carrier> A partnered carrier (Amazon Partnered Carrier Program) uses Amazon-negotiated rates and returns a quote in the transportation option; Small Parcel Delivery has a 24-hour void window, Less-Than-Truckload a 1-hour void window. A non-partnered carrier is one the seller arranges and pays for themselves; it requires a confirmed delivery window before transportation is confirmed, and the seller supplies tracking afterward. The two paths differ in ordering and in what the seller must do after confirmation. </Definition - Partnered vs Non-Partnered Carrier>

<Definition - Shipment Identifier (pre-confirm vs confirmation)> A shipment carries two different ids at different stages, and confusing them breaks label calls. Before placement is confirmed, the shipment has a working shipmentId used within the pipeline. After confirmPlacementOption, it gets a shipmentConfirmationId, and that confirmation id, not the pre-confirm shipmentId, is the one to pass when requesting box or shipment labels. </Definition - Shipment Identifier (pre-confirm vs confirmation)>

<Definition - Active Context> The one merchant account (entityId) plus one marketplace pinned for the session after the connector resolves the seller. Every operation carries this pair. It exists only for the session and is never persisted (Rule 10). </Definition - Active Context>

<Workflow - Manage FBA Inbound description="Drive a seller through the FBA inbound pipeline end to end: create the plan, set packing, choose placement, book transportation, confirm the delivery window where required, and confirm the shipment, pausing at every gate and hard-gating fee-charging confirms." tools=[] triggers=["send inventory to Amazon", "create inbound plan", "ship to FBA", "inbound shipment status", "cancel inbound plan", "add tracking", "FNSKU labels", "prep requirements", "schedule FC drop-off"]

1. [Agent] Confirm the built-in Amazon Selling Partner connector is connected before any work, per the README pre-requisites. Every operation in this pipeline runs through it. Validate: The connector is connected and its inbound operations are reachable. If fails: Tell the seller the Amazon Selling Partner connector must be connected and authenticated (from onboarding or Settings > Capabilities), and stop rather than simulating a result.

2. [Agent] Establish account context (pre-resolved). The connector resolves the seller's merchant account(s) and marketplace(s) at the start of the session. Pin exactly one merchant account (entityId) and one marketplace before any call: if several accounts are in scope, ask which; if several marketplaces are in scope, ask which; if exactly one of each, use it. Keep this context in the session only (Rule 10). Validate: Exactly one entityId and one marketplace are pinned. If fails: If no context is available, tell the seller the connector should resolve it on connect and ask them to confirm the account and marketplace; do not guess an identifier. If more than one is in scope and the seller has not chosen, ask rather than defaulting to the first.

3. [Decide] What does the seller want to do?

   • Create and send a new shipment: continue to step 4.
   • Check status, list plans, add tracking, get labels, see prep, or modify/cancel an existing plan: go to step 11.
   • Something outside inbound scope (stockout forecasting, listing content, ads, orders): route it per Rule 13 and stop.

4. [Agent] Create the inbound plan. Gather the source address, destination marketplace, and items (merchant SKU plus quantity, and the prep and label owner, set to the seller for the US per Gotchas). Call the create-inbound-plan operation, then poll to a confirmed result (Rule 2, Rule 3). Note the inboundPlanId. Validate: The create operation reaches SUCCESS and an inboundPlanId is recorded. If fails: On FAILED, report the exact error and the input that caused it, and ask the seller to correct it. On timeout after the poll cap, hand back the operationId and offer to resume later.

5. [Agent] Set packing information before generating placement (Gotchas). For a pack-first flow, gather each box, its contents, dimensions, and weight and submit them; for a Pack Later flow (Less-Than-Truckload only), submit box dimensions and weight without contents. Poll to a confirmed result. Validate: The packing operation reaches SUCCESS. If fails: On FAILED, report the error and re-collect the box details. If the seller does not yet know contents, switch to the Pack Later flow (see references/special-workflows.md).

6. [Ask user] Confirm the packing option (decision gate). Generate packing options, poll, then list them and present the grouping choices. Wait for the seller to pick one, then confirm it. (Skip generation for the India marketplace per Gotchas.) Packing groups expire in 24 to 72 hours, so note that. Validate: One packing option is confirmed (or, for India, the step is correctly skipped). If fails: If the seller does not choose, re-present the options; do not pick for them (Rule 5).

7. [Ask user] Confirm the placement option (HARD GATE, permanent + placement fee). Generate placement options, poll, then list each with its fulfillment-center split and its placement fee in dollars, and show the fee before asking (Rule 8). Apply the hard gate (Rule 4): the seller explicitly picks one option, you restate the exact choice plus the exact dollar fee plus that it is permanent, and the seller types CONFIRM. Only then confirm the placement option. Validate: The seller typed CONFIRM for a specific option, and the placement confirmation reaches SUCCESS. Record the shipmentConfirmationId (Definitions). If fails: If the seller has not typed CONFIRM, do not confirm; re-present. On a FAILED or expired option, regenerate placement options and repeat the gate.

8. [Agent] Collect transportation inputs, then generate options. Confirm the ready-to-ship date and the ship-from address first (Gotchas), then generate transportation options with the confirmed placement, poll, and list them. Validate: Transportation options are listed for the confirmed placement. If fails: If generation errors on missing inputs, collect the ready-to-ship date or address and retry. If the source address changed, regenerate (it invalidates prior options).

9. [Decide] Is the chosen carrier partnered or non-partnered (Definitions)?

   • Non-partnered: confirm the delivery window (step 10) BEFORE confirming transportation.
   • Partnered: confirm the delivery window only if enrolled in the confirmed-delivery-window program; otherwise continue. Validate: The correct ordering for the carrier type is selected. If fails: If the carrier type is unclear, ask the seller before proceeding.

10. [Ask user] Confirm transportation (HARD GATE, locks carrier + quoted cost). Present carrier, mode, and the quote in dollars, showing the cost before asking (Rule 8). Apply the same hard gate as placement (Rule 4): explicit pick, restate carrier plus exact dollar quote, seller types CONFIRM, then confirm transportation. Confirm the delivery window first if step 9 required it. Then guide the carrier-specific finish (partnered Small Parcel: schedule the carrier pickup; partnered Less-Than-Truckload: bill of lading, freight-ready within 2 weeks; non-partnered: collect tracking and update it). Validate: The seller typed CONFIRM, transportation confirmation reaches SUCCESS, and any required delivery window is confirmed. If fails: If the seller has not typed CONFIRM, do not confirm; re-present. On FAILED, report the error and regenerate before retrying.

11. [Agent] Handle status, management, and extras on request. For an existing plan: list plans, get plan or shipment status, add tracking (non-partnered, after transport is confirmed), get labels (using the shipmentConfirmationId per Gotchas), read or set prep, or handle India compliance and self-ship appointments. For cancellation, apply Rule 7: warn that it voids all shipments and may incur charges outside the void window, and get an explicit confirmation before cancelling. See references/tools-and-additional.md and references/special-workflows.md. Validate: The requested read or management action completes, or the reason it cannot is reported. If fails: Report the exact error and the recovery step; for a cancellation without explicit confirmation, do not cancel.

12. [Agent] Summarize. Recap the stage reached, the shipments and destinations, the carrier and any locked cost, and the single next action the seller must take. Note that placement and transportation costs are the seller's and shipments must comply with Amazon policy (Rule 14). Validate: A short summary with one clear next action is produced. If fails: If any outcome is unknown, say so and offer to re-check the operation status rather than asserting completion.

</Workflow - Manage FBA Inbound>

<Template - Hard Confirm Gate> Use before any permanent, fee-charging confirm (placement, transportation). Never confirm on a vague "ok" (Rule 4).

Confirm required (this is permanent and charges a fee, nothing has been committed yet)

• Action: <confirm placement / confirm transportation>
• Your choice:
• Exact cost:
• Why permanent: <placement cannot be changed for the plan / transportation locks the carrier and quoted cost>

To proceed, type CONFIRM. Any other reply, or a plain "ok" or "yes", will not trigger the change; tell me to adjust instead. </Template - Hard Confirm Gate>

Reference files:

• references/carriers-and-shipping.md: partnered Small Parcel and Less-Than-Truckload vs your own carrier, void windows, bill of lading and pallets, tracking, and the source-address gotcha.
• references/special-workflows.md: the Pack Later (Less-Than-Truckload only) flow and the India marketplace workflow (compliance and self-ship appointments).
• references/tools-and-additional.md: labels, prep, delivery windows, shipment content updates, modify and cancel operations, the read-only inspection operations, key constraints, and common errors.