Skip to main content
POST
/
api
/
Fba
/
FbaShipment
/
create
Create FBA shipment
curl --request POST \
  --url https://api.returnshelper.com/uat/user/api/Fba/FbaShipment/create \
  --header 'Content-Type: application/json' \
  --header 'x-rr-apikey: <api-key>' \
  --header 'x-rr-apitoken: <api-key>' \
  --data '
{
  "createFbaShipmentPayloadList": [
    {
      "trackingNumber": "<string>",
      "warehouseId": 123,
      "removalOrderId": "<string>"
    }
  ]
}
'
{
  "data": [
    {
      "fbaShipmentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "apiId": 123,
      "warehouseId": 123,
      "fbaShipmentStatusCode": "<string>",
      "removalOrderId": "<string>",
      "trackingNumber": "<string>",
      "arrivalOn": "2023-11-07T05:31:56Z",
      "createOn": "2023-11-07T05:31:56Z"
    }
  ]
}
Registers one or more inbound FBA shipments — i.e. tells Return Helper “Amazon dispatched a removal order with this tracking number to this warehouse, expect it.” This is metadata-only: it doesn’t create a label or trigger a physical action; it lets the warehouse correlate an arriving parcel to your removal order when it shows up.

​
When to call

  • After you create a Removal Order in Amazon Seller Central (or via the SP-API), once you have a tracking number from the carrier Amazon assigned.
  • For each shipment within a removal order — Amazon often splits a single removal order into multiple parcels with different tracking numbers; create one FBA shipment per tracking number.

​
Required fields

Each entry in createFbaShipmentPayloadList:
  • trackingNumber — non-empty, single-line, must match a recognised tracking-number format. Globally unique — you cannot reuse a tracking number that’s already on a non-expired FBA shipment record.
  • removalOrderId — Amazon’s removal order ID (e.g. WS-1234567). Single-line, valid format.
  • warehouseId — The warehouse that the FBA is shipping to, must be a warehouse your account is authorised for. Discover via Get all warehouses accessible to user.

​
Cross-payload rules

  • No duplicate trackingNumber within a single batch.
  • Same removalOrderId must always map to the same warehouseId within the batch — you can’t say “removal order WS-1 → warehouse 5” and “removal order WS-1 → warehouse 7” in the same call.

​
Side effects

  • An FbaShipment record is created per payload, linking the tracking number, removal order, and destination warehouse.
  • When the parcel physically arrives, the warehouse uses these records to match it and trigger the fbaShipmentArrived webhook.
  • No label is generated — you’re not shipping; Amazon is.
  • Get FBA shipment details — fetch a single record by fbaShipmentId if a webhook event references one you don’t have cached.
  • Create FBA instructions — once a parcel has arrived (signalled by webhook), instruct the warehouse what to do with the inventory (dispose, recall, replenish, etc.).
  • Webhooks — the FBA shipment lifecycle (arrival, instruction completion, etc.) is delivered exclusively via webhook events.

Authorizations

​
x-rr-apikey
string
header
required

Your API key

​
x-rr-apitoken
string
header
required

Your API token — keep this private

Body

application/json
​
createFbaShipmentPayloadList
object[]
required

List of FBA shipment creation payloads

Response

Success

​
data
object[]

List of created FBA shipments