Fulfillment Inbound API v2024-03-20 Use Case Guide

What is the Fulfillment Inbound API?

The Selling Partner API for Fulfillment Inbound lets you develop applications that create and update inbound plans to ship inventory to Amazon's fulfillment network, where Amazon can fulfill your customer's orders. You can also request lists of inbound shipments or inbound shipment items based on criteria you specify. After your inventory has been received in the fulfillment network, Amazon can fulfill your orders regardless of whether you are selling on Amazon's retail website or through other retail channels. For details about API operations and associated data types and schemas, refer to the Fulfillment Inbound API reference.

Key features

• Create an inbound shipment: The Fulfillment Inbound API accepts POST operations to create new inbound plans and select shipping modes and transportation options to determine the shipments.
• Retrieve details about inbound shipments: The Fulfillment Inbound API accepts GET operations to return detailed information about an existing shipment.
• Update inbound plans: The Fulfillment Inbound API accepts POST operations to update one or more individual attributes for an existing inbound plan, such as updating the inbound plan name or tracking ID.
• Delete inbound plans: The Fulfillment Inbound API accepts a PUT operation to delete an existing inbound plan.
• Interoperability: Plans created with the Fulfillment Inbound API can be accessed and edited on Amazon's UI (called Send to Amazon (STA)) once placement and transportation options are confirmed. You can also use the API to access plans that were created in STA after you confirm placement and transportation options.

⭐

Tip

Use generatePlacementOptions to generate new placement options and generateTransportationOptions to generate new transportation options. If you switch from the API to STA before you confirm your options (with confirmPlacementOption and confirmTransportationOptions), new options are generated in STA and all previous options are discarded.

Terminology

• Amazon-partnered carrier: A carrier who has partnered with Amazon to provide discounted shipping rates.
• Non-Amazon-partnered carrier: A carrier who has not partnered with Amazon to provide discounted shipping rates.
• Small parcel shipment: Units packed in individual boxes that are individually labeled for delivery.
• Less Than Truckload/Full Truckload (LTL/FTL) shipment: Combines individual boxes on pallets for delivery. The truck might contain shipments to other destinations.

Considerations

The following are not supported, but will be supported in the future:

• Creating shipments for the following destination marketplaces:
  • Mexico
  • Brazil
  • Poland
  • Egypt
  • Turkey
  • Saudi Arabia
  • United Arab Emirates
  • India
• Selecting prep category for a SKU

This use case guide mentions two v0 operations that are needed for end-to-end shipment creation: getLabels and getBillOfLading. These operations are not deprecated. You must continue to use these operations to print your box label, pallet label, or bill of lading.

The following v0 operations are not deprecated:

• getLabels
• getBillOfLading
• getPrepInstructions
• getShipments
• getShipmentItemsByShipmentId
• getShipmentItems

Fulfillment Inbound shipment workflow

The following diagram shows the steps to ship inventory to Amazon's fulfillment network. This is an illustrative example and does not include all of the optional operations.

Ship inventory into Amazon's Fulfillment Network

There are two processes that a seller can follow to create a shipment, which differ based on whether the seller knows how their cartons will be packed at the time of shipment creation. In most cases, we expect that sellers would have this information, but there are situations where this information wouldn't be readily available.

Note that the process for creating a shipment when the carton-level information is not known upfront is only available for LTL shipments at this time. This document provides the steps you can follow to ship inventory to Amazon's fulfillment network using either of these processes.

Tutorial: Creating a shipment when the seller knows the carton-level information up-front

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• Approval for the Amazon Fulfillment role and the Product Listing role in your developer profile.
• The Amazon Fulfillment role and Product Listing role selected in the App registration page for your application.
• To have created your listings and understand whether your items are eligible to be shipped to Amazon's fulfillment network (instructions included in optional step section)

Step 1. Create an Inbound Plan

Create an Inbound Plan by calling the asynchronous createInboundPlan operation. An Inbound Plan represents a collection of items that you intend to inbound into Amazon's fulfillment network. By calling the createInboundPlan operation, a seller must specify the following:

• The address from which the inbound shipments will be sent
• The marketplace where the product would be shipped
• A summary of the items that they intend to inbound.

The item summary must include MSKU, quantity, and an indication of who will prepare / label the item. Note that AMAZON can only be selected as the label owner if you are enrolled in the FBA Label Service. For more information about the FBA Label Service, refer to Seller Central Help for your marketplace.

Make sure each item you're shipping conforms to Amazon's product packaging requirements. For more information, refer to Packaging and Prep Requirements in Seller Central Help. For more information about Amazon's product packaging requirements for your marketplace, refer to Seller Central URLs. Note that sellers can set the Prep Category for SKUs on Send to Amazon. This can be done one by one or up to 25 at a time. This is a one-time activity per SKU that carries over to all future inbound plans.

📘

Note

Multiple expiration dates per SKU on a single inbound plan is not supported. To send a SKU with multiple expiration dates to the fulfillment network, you need to create multiple plans.

Optionally, a seller can include each item's expiration date and manufacturing lot code. A successful response includes an inboundPlanId that uniquely identifies the inbound plan, synonymous with the concept of "workflow ID", which is generated on Send to Amazon (the shipment creation workflow on Seller Central).

Body parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans
{
  "destinationMarketplaces" : [ "ATVPDKIKX0DER" ],
  "items" : [ {
    "expiration" : "2024-01-01",
    "labelOwner" : "AMAZON",
    "manufacturingLotCode" : "manufacturingLotCode",
    "msku" : "Sunglasses",
    "prepOwner" : "AMAZON",
    "quantity" : 10
  } ],
  "name" : "My inbound plan",
  "sourceAddress" : {
    "addressLine1" : "123 example street",
    "addressLine2" : "Floor 19",
    "city" : "Toronto",
    "companyName" : "Acme",
    "countryCode" : "CA",
    "email" : "[email protected]",
    "name" : "name",
    "phoneNumber" : "1234567890",
    "postalCode" : "M1M1M1",
    "stateOrProvinceCode" : "ON"
  }
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "operationId1234",
  "inboundPlanId": "PlanID1234"
}

Check the status of a call

Check the status of an inbound request by using the getInboundOperationStatus operation. For asynchronous operations, this operation provides the processing status. We omit this step for other asynchronous operations in this tutorial. By calling getInboundOperationStatus, a seller passes the operationId, which is a Universal Unique Identifier (UUID) for the operation.

A successful response includes the request status and any non-blocking errors associated with the request. Non-blocking errors are warnings that can be ignored (for example, when the address is suspected to be wrong, but progression is allowed anyway).

Path parameters

Request example

GET /inbound/fba/2024-03-20/operations/{operationId}

Response

A successful response includes the following elements:

Response example

{
  "operation": "string",
  "operationId": "string",
  "operationProblems": [
    {
      "code": "Error code 1234",
      "message": "Box volume does not meet the expected minimum cubic cm 144,815",
      "details": "Additional error details",
      "severity": "WARNING"
    }
  ],
  "status": "SUCCESS",
}

Step 2. Determine which SKUs can be packed together

This step is necessary to determine which items can be packed together. Some items cannot be packed together due to differing handling or fulfillment center requirements. There might be a discount for further separating items.

📘

Note

There are only discounted options for Small Parcel Delivery (SPD) shipments in the EU. These discounted options can include additional requirements, including that each package must weigh less than 15 kilograms.

To determine which SKUs can be physically packed together, use the following operations:

• generatePackingOptions
• listPackingOptions
• listPackingGroupItems
• confirmPackingOption

A PackingGroup represents a set of SKUs that can be packed together. SKUs that cannot be packed together go into different pack groups. For example, SKUs that are classified as dangerous goods cannot be packed with other SKUs, because dangerous goods SKUs are shipped to special fulfillment centers that can receive them safely. Other factors that determine which SKUs can and cannot be packed together include SKU weights and dimensions, prep and labelling requirements, and barcode requirements.

The PackingOptions object represents the set of options for how items are mapped to packing groups. Each PackingOption includes a set of PackingGroups, which each contain a list of SKUs. Each of these options can have discounts or fees associated with them. Also, each option can be limited to a subset of all possible shipping modes. These packing operations enable the seller to review and select an option.

Step 2a. Generate packing options

First, generate packing options with the generatePackingOptions operation.

Path parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string",
  "inboundPlanId": "string"
}

Step 2b. List packing options

Next, review a list of the packing options with the listPackingOptions operation. Packing options contain sets of pack groups that a seller can choose, along with additional information that can help a seller choose between these options. Additional information includes fees/discounts associated with each option, shipping modes supported by each option, and the expiration date of each option.

Path parameters

Query parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions

Response

A successful response includes the following elements:

Response example

{
  "pagination": {
    "nextToken": "string"
  },
  "packingOptions": [
    {
      "inboundPlanId": "string",
      "packingOptionId": "string",
      "packingGroups": [
        "string"
      ],
      "fees": [
        {
          "currency": {
            "code": "string",
            "amount": 0
          },
          "type": "FEE",
          "target": "OUTBOUND_PER_SHIPMENT",
          "description": "string"
        }
      ],
      "discounts": [
        {
          "currency": {
            "code": "string",
            "amount": 0
          },
          "type": "FEE",
          "target": "OUTBOUND_PER_SHIPMENT",
          "description": "string"
        }
      ],
      "expiration": "2019-08-24T14:15:22Z",
      "status": "OFFERED",
      "supportedShippingModes": [
        {
          "shippingSolution": "AMAZON_PARTNERED_CARRIER",
          "shippingMode": "GROUND_SMALL_PARCEL"
        }
      ]
    }
  ]
}

Step 2c. List items in each packing option

To view the items in each packing group, use the listPackingGroupItems operation.

Path parameters

Query parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingGroups/{packingGroupId}/items

Response

A successful response includes the following elements:

Response example

{
  "pagination": {
    "nextToken": "string"
  },
  "items": [
    {
      "msku": "string",
      "asin": "string",
      "fnsku": "string",
      "labelOwner": "AMAZON",
      "quantity": 1,
      "prepOwner": "AMAZON"
    }
  ]
}

Step 2d. Select a packing option

Choose a packing option with the confirmPackingOption operation.

Path parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingOptions/{packingOptionId}/confirmation

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

Step 3. Provide box content information

To provide information related to the items that will be packed into each box, use the setPackingInformation operation. Providing this information ensures that the shipment splits generated in the subsequent step (generatePlacementOptions) are accurate. If no box information is provided at this step, the shipment splits generated in the next step are based only on the unit information passed to Amazon as part of createInboundPlan. By calling setPackingInformation, a seller must pass the following information for each box that they intend to inbound:

• Packing group ID
• Box content information source
• Box contents (items, item quantities, prep/label owners for each item)
• Box information (dimensions, weight, and quantity of boxes)

📘

Note

If a seller provides box packing information using setPackingInformation, generates placement options, and then edits their box packing information using setPackingInformation, then the seller needs to call generatePlacementOptions again prior to calling confirmPlacementOption. If a seller inputs their box packing information using setPackingInformation and then decides that they want to discard this information entirely, they need to start a new inbound plan with createInboundPlan. Discarding packing information is not currently supported.

Box content information source indicates how the seller intends to provide box content information, which could be through one of three options:

• Populating the Contents field (BOX_CONTENT_PROVIDED)
• Paying Amazon a fee to enter this information during the receiving process (MANUAL_PROCESS)
• Affixing 2D barcodes to the boxes (BARCODE_2D)

The seller must also provide box dimensions, box weight, and the quantity of each box. When boxAttribute is set toBARCODE_2D or MANUAL_PROCESS:

• You don't need to provide SKUs and quantities.
• You must leave items empty (provide a null value).

A successful response includes the operationId that can be used to determine the status of the operation using getInboundOperationStatus.

📘

Note

In this flow, pass in the PackingGroupId but omit the ShipmentId.

Path parameters

Body parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/packingInformation
{
  "packageGroupings": [
    {
      "packingGroupId": "string",
      "boxes": [
        {
          "weight": {
            "unit": "LB",
            "value": 0
          },
          "dimensions": {
            "unitOfMeasurement": "IN",
            "length": 0,
            "width": 0,
            "height": 0
          },
          "quantity": 1,
          "boxId": "string",
          "items": [
            {
              "msku": "string",
              "quantity": 1,
              "expiration": "string",
              "prepOwner": "AMAZON",
              "labelOwner": "AMAZON",
              "manufacturingLotCode": "string"
            }
          ],
          "contentInformationSource": "BOX_CONTENT_PROVIDED"
        }
      ]
    }
  ]
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

Step 4. Generate and view options for destination fulfillment centers

Generate placement options for an inbound plan by calling the generatePlacementOptions operation. The PlacementOptions object represents the set of available placement options for an inbound plan, where each placement option describes the destination FCs and shipping options for each item in your inbound plan. These options help reduce the time it takes to receive a seller's items and make them available for sale (refer to Seller Central Help for more details).

📘

Note

This operation generates initial shipment IDs for the shipments within each inbound plan. These IDs are different from the shipmentConfirmationIDs that confirmPlacementOption generates. The shipmentConfirmationID is the ID that is present on labels (for example, FBA1234ABCD). You can retrieve both of these shipment ID types with the getShipment operation.

Some of your options can include multiple destinations (refer to Seller Central Help for details). Each option can include fees or discounts, which are determined using an algorithm when your shipment is being created, and is not calculated using a set rate. The algorithm for the rebate value and the ship-to location uses multiple factors to optimize your shipments, including expected volume, the availability of carrier appointments, and fulfillment speed. The rebate that your shipment is eligible for is provided during shipment creation.

The terms and conditions can change. Review the current Seller Central terms and conditions, including the Amazon Services Business Solutions Agreement.

Path parameters

Body parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions
{
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

To view the options for shipment splits, call the listPlacementOptions operation. This operation provides the list of available placement options, which include:

• A placement option ID
• The option status ("offered" or "accepted")
• Any fees/discounts associated with this option
• The expiration date of the option
• The shipment IDs associated with each option

When a placement option expires, you must regenerate placement options by calling generatePlacementOption. The placement option ID is required to generate transportation options with generateTransportationOptions, while shipment IDs are used to understand the contents of each shipment using getShipment.

Path parameters

Query parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions

Response

A successful response includes the following elements:

Response example

{
  "pagination": {
    "nextToken": "string"
  },
  "placementOptions": [
    {
      "inboundPlanId": "string",
      "placementOptionId": "string",
      "status": "OFFERED",
      "fees": [
        {
          "currency": {
            "code": "string",
            "amount": 0
          },
          "type": "FEE",
          "target": "OUTBOUND_PER_SHIPMENT",
          "description": "string"
        }
      ],
      "discounts": [
        {
          "currency": {
            "code": "string",
            "amount": 0
          },
          "type": "FEE",
          "target": "OUTBOUND_PER_SHIPMENT",
          "description": "string"
        }
      ],
      "expiration": "2019-08-24T14:15:22Z",
      "shipmentIds": [
        "string"
      ]
    }
  ]
}

Step 5. Input transportation data and generate transportation options

Generate transportation options with the generateTransportationOptions operation. A transportation option represents the list of shipping mode and carrier options that are available for each shipment within each placement option. By calling generateTransportationOptions, a seller must pass the following information:

• Placement option ID
• Shipment ID
• Ready to ship date
• Ship from address

Path parameters

Body parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions
{
  "placementOptionId": "string",
  "shipmentTransportationConfigurations": [
    {
      "shipmentId": "string",
      "readyToShipWindow": {
        "start": "2019-08-24T14:15:22Z"
      },
      "contactInformation": {
        "phoneNumber": "string",
        "email": "string",
        "name": "string"
      },
      "palletInformation": {
        "pallets": [
          {
            "weight": {
              "unit": "LB",
              "value": 0
            },
            "dimensions": {
              "unitOfMeasurement": "IN",
              "length": 0,
              "width": 0,
              "height": 0
            },
            "quantity": 1,
            "stackability": "STACKABLE"
          }
        ],
        "freightClass": "string",
        "declaredValue": {
          "code": "str",
          "amount": 0
        }
      }
    }
  ]
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

Step 6. Generate delivery window options with the generateDeliveryWindowOptions operation

🚧

Important

Sellers must confirm transportation options for all shipment types. For non-partnered shipments, sellers must also specify a delivery window.

Delivery windows are periods during which a seller can deliver their shipment to the destination fulfillment center. If the seller uses a non-partnered carrier, they must specify a seven-day delivery window for domestic shipments or a 14-day window for international shipments. The window is used to provide a shipment's expected arrival date and time at an Amazon fulfillment center. An available delivery window option is necessary for shipments that don't have an appointment slot with a fulfillment center. For example, shipments through non-partnered carriers need a confirmed delivery window.

generateDeliveryWindowOptions requires the seller to pass the shipmentID for the shipment for which they intend to generate delivery windows.

Path parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions

Response

Response example

{
  "operationId": "string"
}

Step 7. Review shipment splits and transportation options

Review shipment and transportation options by calling the listPlacementOptions, listTransportationOptions, and getShipment operations.

listPlacementOptions provides the list of available placement options, which includes a placement option ID, the status of the option (that is, offered vs. accepted), any fees/discounts associated with this option, the expiration date of the option, and the shipment IDs associated with each option.

To call listTransportationOptions, a seller needs to pass the placement option ID and shipment ID for which they want to view transportation options. A successful response includes all available transportation quotes for all available ship modes and carrier options. Shipping modes include:

• Ground small parcel
• Less-than-truckload freight
• Full truckload freight (palletized)
• Full truckload freight (non-palletized)
• Less than container load ocean
• Full container load ocean
• Air small parcel
• Air small parcel express

Carrier options include Amazon-partnered and non-partnered carriers. Quotes include:

• Cost
• A void window (the period where a seller can cancel a shipment and receive a refund for their transportation quote)
• Expiration

In regions where fulfillment center appointments are mandatory (for example, India), we provide available appointment slots.

Where the Partnered Carrier Program (PCP) is available, sellers can take advantage of discounted rates by using an Amazon-partnered carrier for their inbound shipments. To use an Amazon-partnered carrier for an inbound shipment, select the transportation option where shippingSolution is AMAZON_PARTNERED_CARRIER.

📘

Note

Before you use an Amazon-partnered carrier for an inbound shipment, you must read the Seller Central Help about Amazon's PCP to help ensure that you successfully follow the program instructions and guidelines (Europe) (US).

In the EU region, you must first review and accept the terms and conditions of the carrier and the terms and conditions of Amazon's PCP. You can do this on Seller Central. If you attempt to use Amazon Selling Partner APIs to create an inbound shipment by using an Amazon-partnered carrier before accepting these terms and conditions, the service returns an error.

If a seller doesn't want to participate in the PCP, they can view Choose your own carrier transportation options and available shipping modes.

Amazon filters out partnered carrier transportation options in certain situations. For example, if there is a partnered carrier transportation option at a lower price for a placement option that has identical shipment splits, then Amazon filters out the more expensive transportation option. If you plan to use a partnered carrier, call listTransportationOptions for each placement option to see the available partnered carrier options.

📘

Note

You can include a mix of Small Parcel Delivery (SPD) and LTL shipments in one inbound plan. You can also include a mix of PCP and non-PCP shipments in one inbound plan if:

• The different carrier selections are assigned to different shipping modes (for example SPD and LTL).
• All shipments in the inbound plan are eligible for PCP.

For example, you can create an inbound plan with one PCP SPD shipment and one non-PCP LTL shipment, assuming that all shipments within the inbound plan are eligible for PCP.

For more information about PCP eligibility, refer to the PCP help page.

Path parameters

Query parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions

Response

A successful response includes the following elements:

Response example

{
  "pagination": {
    "nextToken": "string"
  },
  "transportationOptions": [
    {
      "inboundPlanId": "string",
      "placementOptionId": "string",
      "shipmentId": "string",
      "transportationOptionId": "string",
      "shippingSolution": "AMAZON_PARTNERED_CARRIER",
      "carrier": {
        "name": "string",
        "alphaCode": "string"
      },
      "shippingMode": "GROUND_SMALL_PARCEL",
      "quote": {
        "cost": {
          "code": "string",
          "amount": 0
        },
        "voidableUntil": "2019-08-24T14:15:22Z",
        "expiration": "2019-08-24T14:15:22Z"
      },
      "appointmentSlot": {
        "startDate": "2019-08-24T14:15:22Z",
        "endDate": "2019-08-24T14:15:22Z",
        "startTime": "2019-08-24T14:15:22Z",
        "endTime": "2019-08-24T14:15:22Z"
      }
    }
  ]
}

Review available delivery window options for each shipment within an inbound plan using the listDeliveryWindowOptions operation. To make this call, a seller passes the shipmentID. A successful response provides the startDate and endDate for each available delivery window and the level of congestion (availabilityType) for each option.

🚧

Important

Sellers must confirm transportation options for all shipment types. For non-Amazon partnered shipments, they must also specify a delivery window.

Each option has an expiration date (validUntil). You must confirm the delivery before this date. If you don't confirm the window by the validUntil date, you must generate a new window using listDeliveryWindowOptions.

Path parameters

Query parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/deliveryWindowOptions

Response

A successful response includes the following elements:

Response example

{
  "pagination": {
    "nextToken": "string"
  },
  "deliveryWindowOptions": [
    {
      "inboundPlanId": "string",
      "placementOptionId": "string",
      "shipmentId": "string",
      "deliveryWindowOptionId": "string",
      "startDate": "2019-08-24T14:15:22Z",
      "endDate": "2019-08-24T14:15:22Z",
      "availabilityType": "string",
      "validUntil": "2019-08-24T14:15:22Z"
    }
  ]
}

Review details related to the contents of a shipment within an inbound plan using the getShipment operation. To call getShipment, a seller needs to pass the inbound plan ID and shipment ID. A successful response includes the following:

• Placement option ID
• Shipment confirmed ID (the ID that shows up on labels)
• Shipment ID (the identifier for a shipment prior to the confirmPlacementOption operation)
• Amazon reference ID (identifier for scheduling fulfillment center appointments for truck deliveries)
• Selected transportation option ID
• Name
• Source
• Destination FC
• Ship date
• Estimated delivery date
• Status
• Tracking details
• Pallet information
• Contact information
• Destination region
• FC appointment details

Path parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}

Response

A successful response includes the following elements:

Response example

{
  "inboundPlanId": "string",
  "placementOptionId": "string",
  "shipmentId": "string",
  "shipmentConfirmationId": "string",
  "amazonReferenceId": "string",
  "selectedTransportationOptionId": "string",
  "name": "string",
  "source": {
    "sourceType": "SELLER_FACILITY",
    "address": {
      "name": "string",
      "companyName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "countryCode": "st",
      "stateOrProvinceCode": "string",
      "postalCode": "string"
    }
  },
  "destination": {
    "destinationType": "AMAZON_OPTIMIZED",
    "address": {
      "name": "string",
      "companyName": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "countryCode": "st",
      "stateOrProvinceCode": "string",
      "postalCode": "string"
    },
    "warehouseId": "string"
  },
  "dates": {
    "readyToShipWindow": {
      "start": "2019-08-24T14:15:22Z",
      "end": "2019-08-24T14:15:22Z",
      "editableUntil": "2019-08-24T14:15:22Z"
    },
    "deliveryWindow": {
      "start": "2019-08-24T14:15:22Z",
      "end": "2019-08-24T14:15:22Z",
      "editableUntil": "2019-08-24T14:15:22Z"
    }
  },
  "status": "ABANDONED",
  "trackingDetails": {
    "ltlTrackingDetail": {
      "freightBillNumber": [
        "string"
      ],
      "billOfLadingNumber": "string"
    },
    "spdTrackingDetail": {
      "spdTrackingItems": [
        {
          "boxId": "string",
          "trackingId": "string",
          "trackingNumberValidationStatus": "VALIDATED"
        }
      ]
    }
  },
  "palletInformation": {
    "pallets": [
      {
        "weight": {
          "unit": "LB",
          "value": 0
        },
        "dimensions": {
          "unitOfMeasurement": "IN",
          "length": 0,
          "width": 0,
          "height": 0
        },
        "quantity": 1,
        "stackable": true
      }
    ],
    "freightClass": "NONE",
    "declaredValue": {
      "code": "string",
      "amount": 0
    }
  },
  "contactInformation": {
    "phoneNumber": "string",
    "email": "string",
    "name": "string"
  },
  "selfShipAppointmentDetails": [
    {
      "appointmentId": 0,
      "appointmentSlotTime": {
        "startTime": "2019-08-24T14:15:22Z",
        "endTime": "2019-08-24T14:15:22Z"
      },
      "appointmentStatus": "string"
    }
  ]
}

Step 8. Select shipping option

Select shipment option (that is, shipment splits) with the confirmPlacementOption operation. This operation selects the placement splits for an inbound plan and creates confirmed shipment IDs for shipments within the inbound plan. The shipmentConfirmationID is the shipment identifier that appears on labels (for example, FBA1234ABCD). This ID is different from the shipment ID that is generated with createInboundPlan, which is used as an input to other operations, such as getShipment. This option cannot be reversed after it is selected. To call confirmPlacementOption, a seller must pass the inbound plan ID and the selected placement option ID.

📘

Note

createInboundPlan generates initial shipment IDs for the shipments in each inbound plan. These IDs are different from the shipmentConfirmationIDs that confirmPlacementOption generates. The shipmentConfirmationID is the identifier that is present on labels (for example, FBA1234ABCD). You can retrieve both types of shipment IDs with the getShipment operation.

Path parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/placementOptions/{placementOptionId}/confirmation

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

Step 9. Select transportation options

Select delivery windows for each shipment within a plan using the confirmDeliveryWindowOptions operation. To call this operation, pass the shipmentID and deliveryWindowOptionId (provided by listDeliveryWindowOptions).

You must confirm a placement option for the shipment before you call this operation. After you confirm the delivery window, new delivery window options cannot be generated. However, you can update the selected delivery window option before shipment closure. For all transportation options that have the program DELIVERY_WINDOW_REQUIRED, you must confirm a delivery window before you confirm the transportation option. If you need to update your delivery window after you confirm the transportation option, you can call confirmDeliveryWindow.

Path parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/deliveryWindowOptions/confirmation
{
  "transportationSelections": [
    {
      "shipmentId": "string",
      "transportationOptionId": "string",
      "contactInformation": {
        "phoneNumber": "string",
        "email": "string",
        "name": "string"
      }
    }
  ]
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

This mandatory step allows you to select transportation options for each shipment within an inbound plan using the confirmTransportationOptions operation. For Amazon-partnered transportation options, this operation confirms that the seller accepts the Amazon-partnered shipping estimate, agrees to allow Amazon to charge their account for the shipping cost, and requests that the Amazon-partnered carrier ships the inbound shipment. Before this call, a seller must confirm a placement option for their inbound plan. To call confirmTransportationOptions, a seller must pass the shipment ID, selected transportation option ID, and contact information (needed for partnered carriers for LTL shipments). When a transportation option is confirmed, new transportation options cannot be generated or confirmed for an inbound plan. You must confirm a transportation option before printing labels.

📘

Note

If a seller confirms the transportation request, then decides they don't want the Amazon-partnered carrier to ship the inbound shipment, they can use cancelInboundPlan to cancel the transportation request. For Small Parcel shipments, the seller has 24 hours after confirming a transportation request to void the request. For Less Than Truckload/Full Truckload (LTL/FTL) shipments, the seller has one hour after confirming a transportation request to void the request. After the relevant time period expires, the seller's account is charged for the shipping cost.

Path parameters

Body parameters

Request example

POST /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/transportationOptions/confirmation
{
  "transportationSelections" : [ {
    "contactInformation" : {
      "email" : "[email protected]",
      "name" : "John Smithy",
      "phoneNumber" : "1234567890"
    },
    "deliveryWindow" : {
      "start" : "2024-01-01T00:00Z"
    },
    "shipmentId" : "sh1234abcd-1234-abcd-5678-1234abcd5678",
    "transportationOptionId" : "to1234abcd-1234-abcd-5678-1234abcd5678"
  } ]
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

Step 10. Printing labels

Call the getLabels operation to request unique shipping labels for your inbound shipments. Each shipping label returned by the getLabels operation should be affixed to the package in the shipment that it corresponds to, so the labels indicate the package contents. This helps to ensure that your shipment is processed at the Amazon fulfillment center quickly and accurately.

❗️

Warning

The value of shipmentId in the getLabels request must be the shipmentId (from v0) or the shipmentConfirmationId (from v2024-03-20). Do not use the shipmentId from v2024-03-20.

To print labels for a specific box, specify the boxID (from the listShipmentBoxes response) as the PackageLabelsToPrint value.

Note that the shipment status does not become ready_to_ship if you retrieve carton labels with getLabels. For a shipment status to become ready_to_ship, you must generate labels on Send to Amazon.

For detailed instruction, refer to Request shipping labels for your inbound shipment.

Step 11. Send your shipments to Amazon's fulfillment network

Send your shipments to Amazon's fulfillment network using an Amazon-Partnered carrier or a non-Amazon-Partnered carrier that is registered with Amazon. For more information about sending shipments to Amazon's fulfillment network, refer to the Seller Central Help for your marketplace.

As you prepare your shipment, you can retrieve all of the box-level information that you have entered for an inbound plan using the listInboundPlanBoxes operation.

Path parameters

Query parameters

Request example

GET /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/boxes

Response

A successful response includes the following elements:

Response example

{
  "pagination": {
    "nextToken": "string"
  },
  "boxes": [
    {
      "packageId": "string",
      "weight": {
        "unit": "LB",
        "value": 0
      },
      "dimensions": {
        "unitOfMeasurement": "IN",
        "length": 0,
        "width": 0,
        "height": 0
      },
      "quantity": 0,
      "boxId": "string",
      "templateName": "string",
      "items": [
        {
          "msku": "string",
          "asin": "string",
          "fnsku": "string",
          "labelOwner": "AMAZON",
          "quantity": 1,
          "expiration": "string",
          "manufacturingLotCode": "string",
          "prepInstructions": [
            {
              "prepType": "string",
              "prepOwner": "AMAZON",
              "fee": {
                "code": "string",
                "amount": 0
              }
            }
          ]
        }
      ],
      "shipmentId": "string",
    }
  ]
}

Step 12. Providing tracking information

After sending a shipment to Amazon's fulfillment network using a non-partnered carrier, a seller must share the tracking ID using the updateShipmentTrackingDetails operation. To call this operation, a seller must pass the shipment ID and tracking details for their less-than-truckload or small parcel shipment. For less-than-truckload shipments, the seller must provide a PRO number (also known as Freight Bill number) and can optionally provide a BOL number. For small parcel shipments, the seller must share an array of box IDs and associated tracking IDs.

Path parameters

Body parameters

Request example

PUT /inbound/fba/2024-03-20/inboundPlans/{inboundPlanId}/shipments/{shipmentId}/trackingDetails
{
  "trackingDetails": {
    "ltlTrackingDetail": {
      "freightBillNumber": [
        "string"
      ],
      "billOfLadingNumber": "string"
    },
    "spdTrackingDetail": {
      "spdTrackingItems": [
        {
          "boxId": "string",
          "trackingId": "string"
        }
      ]
    }
  }
}

Response

A successful response includes the following elements:

Response example

{
  "operationId": "string"
}

Tutorial: Creating a shipment when the seller does not know the carton level information up-front

Step 1. Create an Inbound Plan

📘

Note

The process for creating a shipment when the carton-level information is not known upfront is only available for LTL shipments.

Create an Inbound Plan by calling the asynchronous createInboundPlan operation. An Inbound Plan represents a collection of inbound shipments that contain items you intend to inbound into Amazon's fulfillment network. By calling the createInboundPlan operation, a seller must specify:

• The address from which the inbound shipments will be sent
• The marketplace where the product would be shipped
• Contact information (needed for partnered carriers for LTL shipments)
• A summary of the items they intend to inbound

The item summary must include MSKU, quantity, and an indication of who will prepare/label the item. Note that AMAZON_LABEL is available only if you are enrolled in the FBA Label Service. For more information about the FBA Label Service, refer to the Seller Central Help for your marketplace.

Make sure each item you ship conforms to Amazon's product packaging requirements. For more information, refer to Packaging and Prep Requirements in Seller Central Help. For more information about Amazon's product packaging requirements for your marketplace, refer to Seller Central URLs. You can set the Prep Category for SKUs on Send to Amazon Step 1. You can do this one at a time or up to 25 at a time. This is a one-time activity per SKU that carries over to all future inbound plans.

📘

Note

Multiple expiration dates per SKU on a single inbound plan is not supported. To send a SKU with multiple expiration dates to the fulfillment network, you need to create multiple plans.

Optionally, a seller can include each item's expiration date and manufacturing lot code. A successful response includes an inboundPlanId, which is a unique identifier for the inbound plan, synonymous with the concept of "workflow ID", which is generated on Send to Amazon (the shipment creation workflow on Seller Central).

📘

Note

createInboundPlan generates initial shipment IDs for the shipments within each inbound plan. These IDs are different from the shipmentConfirmationIDs that are generated with the confirmPlacementOption operation. The shipmentConfirmationID is the identifier that appears on labels (for example, FBA1234ABCD). Both of these types of shipment IDs can be retrieved with the getShipment operation.

Body parameters