FBA Workflow

The FBA workflow creates an Amazon inbound plan from an outbound shipment, submits packing information, lets Amazon choose where the inventory is sent, confirms transportation, then requests labels. Most stages are asynchronous on Amazon's side and follow the same three-part pattern described below.

The plan object is the source of truth between calls. After every operation completes, reload the plan with GET /plans/{plan_id} and read the IDs you need from the refreshed response rather than reusing IDs from an earlier call.

This is the single most important thing to understand. Almost every stage is three calls, not one:

1. Dispatch — a generate-* or confirm-* call that sends an async request to Amazon and returns an operation id.
2. Poll — drive that operation to SUCCESS with GET /operations/{id}/update.
3. Commit — a select-* or mark-*-as-confirmed call that records the confirmation on the plan.

The mark-*-as-confirmed and select-* calls are local: they do not call Amazon, they record the confirmation (and, for transportation, release a lock). Always poll the operation, not the plan — the plan's updated_at does not move while an operation is running, which is not a sign of failure.

Every option, group, and box in the plan response carries two identifiers: our internal id (a UUID) and Amazon's id (for example packing_option_id, placement_option_id, or a box's amazon_box_id). Sending the wrong one is a common cause of “not found / is null” errors. Which id each endpoint expects:

You need an outbound shipment, an Amazon channel, and one or more merchant SKUs with quantities. The SKUs must exist on the Amazon channel and be eligible for inbound shipment. Check eligibility and prep details before creating the plan — the cached endpoints avoid a live Amazon fetch, while fetch-item-eligibility asks Amazon for the latest eligibility of one ASIN.

Create the plan from the outbound shipment. createInboundPlan accepts only msku, quantity, prep_owner, label_owner, and expiration. Amazon does not take an FNSKU or ASIN here, so a freshly created plan item always has fnsku: null and asin: null. That is expected — see When FNSKUs get stamped below.

If creation rejects an item (for example brand approval, FBA_INB_0021), the reason is on the create operation's problems array, not on the plan items — see Reading per-item errors.

Set whether packing information is known before placement with update-packing-info-known. Use pack first for small parcel and any flow where box contents are known up front. Use pack later when placement must be confirmed before cartons are finalized, most commonly for LTL. Pack later does not support small parcel in the current workflow.

If generate-packing-options returns SUCCESS but packing_options stays empty, Amazon found no valid packing arrangement for the plan. Re-firing will not change it. This is almost always an item-level eligibility or compliance problem (or the plan errored), so check item eligibility and the create operation's problems rather than retrying.

Plan items are created with fnsku: null and asin: null. Nothing back-fills them on a timer, and set-packing-information reaching SUCCESS does not stamp them. They are written onto the plan items only when you read the items back from Amazon through packing-group-items (before placement) or list-shipment-items (after placement). That same fetch is what assigns Amazon box IDs downstream, so if the FNSKU never lands, the box never gets an amazon_box_id and tracking and labels both fail with “one or more items are missing an FNSKU.”

A box group describes one package size and weight plus the associated Amazon packing group or shipment. Create box groups, set quantities, and add plan items, then call set-packing-information and drive its operation to SUCCESS. Commit the box contents with add-carton-request-to-submission, passing each packing group's id.

There is no mark-packing-information-as-confirmed route. add-carton-request-to-submission is the call that finalizes packing information.

Placement options describe how Amazon wants the plan split across fulfillment centers and what fees or discounts apply. Generate options, select one, then confirm it (dispatch, poll, commit). If you regenerate or re-pull placement options after confirming, the confirmation is cleared along with any delivery-window and transportation selections, so do not regenerate placement once you have moved past it.

After placement is confirmed, call set-boxes-ids. It requires a confirmed placement and assigns Amazon box IDs to the shipment. Until it runs, the boxes have contents on our side but are not assigned on Amazon, and confirm-transportation-option and request-box-labels reject with “Boxes are assigned incorrectly for the shipment.”

Amazon assigns the per-box amazon_box_id (the FBA… value) shortly after placement is confirmed, and set-boxes-ids is what reads it from Amazon and stamps it onto the box. Read the stamped id from get-shipment, in the boxes[].amazon_box_id field (or nested under placement_options[].shipments[].boxes[] on the plan response). Do not poll list-shipment-boxes for it: that endpoint returns box-group geometry and contents only and has no box-id field, so the id never appears there. If boxes[] is empty on get-shipment, set-boxes-ids has not run since placement was confirmed.

When a transportation option lists PRECONDITIONS: CONFIRMED_DELIVERY_WINDOW (typical for non-partnered shipments), confirm a delivery window first. Set the first availability date and transport mode, generate windows, then confirm and commit the chosen window.

The generate-delivery-window operation can sit at IN_PROGRESS even after the windows are listable — this is Amazon eventual consistency. It is safe to pick from the listed options; what matters is that the confirm-delivery-window-option operation reaches SUCCESS, then run the mark step.

Generate transportation options after placement is confirmed and boxes are assigned. Confirm one option per shipment (shipment_transportation_ids), drive the operation to SUCCESS, then call mark-transportation-option-as-confirmed. Transportation options can expire; regenerate if they are more than about 15 minutes old.

For dangerous goods, Amazon does not quote a partnered carrier, so generate-transportation-options can run for a couple of minutes and return zero partnered options. That is expected. The signal to go non-partnered is the option set coming back entirely as USE_YOUR_OWN_CARRIER with no partnered option present; confirm the own-carrier option (for example Deutsche Post DHL), then write tracking.

update-tracking-small-details requires a confirmed non-PCP (own-carrier) transportation option — otherwise Amazon returns “can only be processed for shipments that have confirmed a non-PCP transportation option.” Send the box's amazon_box_id (the FBA… value), not the internal box id. Read that id from get-shipment (boxes[].amazon_box_id). If it is empty, run set-boxes-ids (it needs a confirmed placement) to stamp it, then re-read get-shipment.

A plan can use Amazon 2D barcodes for box content: set-packing-information sends contentInformationSource: BARCODE_2D for each box. On a 2D-barcode plan the 4x6 box label is generated by PrepBusiness from the box's FNSKU and contents rather than requested from Amazon, so request-box-labels produces the label without an Amazon-assigned box id. Every item in the box must have a stamped FNSKU, or the call rejects with “one or more items are missing an FNSKU.”

set-boxes-ids is a single GET with no body and no operation to poll — the 202 only means it finished. It matches the boxes Amazon has returned to your plan boxes and stamps each amazon_box_id onto the box; it does not create boxes on Amazon. Once placement is confirmed, run set-boxes-ids, then read the stamped id from get-shipment (boxes[].amazon_box_id), not from list-shipment-boxes.

Request labels only after transportation is confirmed (and, for non-partnered, after tracking is saved). FNSKUs must already be stamped or box labels reject. Labels generate asynchronously, so the first poll of the labels endpoint usually returns nothing.

When a plan will not progress, the per-item reasons the dashboard shows are not on GET /plans/{plan_id}. There are two sources. Item eligibility, approval, and compliance (for example “Approval is required before this item can be sent”) come from the eligibility endpoints, keyed by ASIN, in ineligibilityReasons. Rejections from plan creation come from the create-plan operation's problems array, with the SKU or FNSKU inside the message and details.

Canceling is its own dispatch-poll-commit flow. Run cancel-plan-checker first for warnings (for example a confirmed partnered carrier), then cancel-plan, drive its operation to SUCCESS, then mark-plan-as-canceled. The plan stays ACTIVE until the mark step sets its status to voided locally — cancel-plan succeeding on its own does not flip is_canceled.

Use POST /plans/{plan_id}/update to pull the latest Amazon state. Use reset endpoints (reset-placement-options, reset-submissions) only when intentionally backing up to an earlier stage, because later selections or submissions are cleared. If Amazon reports placement options were generated in Seller Central, regenerate them through the API before continuing.