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

This tutorial describes how to create a shipment when the seller does not know carton-level information.

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)

Workflow

The following table outlines the steps to create a shipment when the seller does not know carton-level information. This table is an illustrative example and does not include all of the optional operations.

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.

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 can include a list of errors associated with the request.

Step 2. Generate and view options for destination fulfillment centers

Generate and view placement options for an inbound plan by calling the generatePlacementOptions, listPlacementOptions, and getShipment operations.

🚧

Warning

Sellers cannot provide packing information using Send to Amazon after confirming placement options. They will not be able to access API-created shipments on Send to Amazon during this step.

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 are designed to help reduce the time that it takes to receive a seller's items and make them available for sale (refer to Seller Central Help for more details).

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.

📘

Note

When a seller calls generatePlacementOptions without inputting box content information, Amazon provides placement options that are optimized for unit-level data (because Amazon does not yet have box data). These options can differ from the placement options that are generated after a seller provides box content information (using setPackingInformation).

View the options for shipment splits by calling 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 (refer to the following).

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 placement option ID, shipment confirmed ID (that is, the ID that shows up on labels, created after confirmPlacementOption), shipment ID (that is, 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, and FC appointment details.

Step 3. Select shipping option

Select shipping options with the confirmPlacementOption operation. This operation selects the placement option 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 differs from the initial shipment ID generated by createInboundPlan. 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

Quotes are only returned for transportation options that are associated with PCP shipments. Expiry date and void window are only returned for transportation options that are confirmed with confirmTransportationOptions.

Step 4. Provide box content information

❗️

Important

This is a mandatory step. If you do not call setPackingInformation, there may be defects in the receiving process and fees for manual processing. For more information, refer to FBA manual processing fee.

📘

Note

You need to know which items are associated with each shipment before you call setPackingInformation. You can get this information on STA and from the API. If you pass incorrect information, you receive an error message with the expected quantities. You can also retrieve this information for your shipment on Send to Amazon.

Provide information related to what items will be packed into each box by using the setPackingInformation operation. By calling setPackingInformation, a seller must pass the following information for boxes they intend to inbound:

• The package grouping ID (that is, the shipment ID of the confirmed placement option) of every shipment
• Box content information source
• Box contents (items, item quantities, prep/label owners for each item)
• Box information (dimensions, weight, and quantity of boxes)

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

⭐

Tip

In this flow, include ShipmentId and omit PackingGroupId.

List shipment items

View a paginated list of items in a shipment by calling the listShipmentItems operation. Sellers must pull this information to understand which items are in each shipment split when they haven't input the carton level information upfront. To call this API, a seller must pass the shipment ID. A successful response contains a paginated list of the products the user previously entered using the createInboundPlan operation. The response contains the prep instructions for their ASINs, such as prep type and owner. This allows users to conveniently check what items and prep requirements are in a given shipment. The response lists the product’s MSKU, ASIN, FNSKU, Manufacturer Code, quantity, and expiration date if needed. This can be used to generate a pick list which they can use to pull certain items from their inventory and group them into a shipment. The seller then uses the listShipmentBoxes operation to create a pack list that specifies which items go in which boxes.

Step 5. Input transportation data, generate transportation options, and view options

Generate transportation options with the generateTransportationOptions operation. A transportation option represents the list of available 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
• Expected delivery date
• Ship from address, and optionally
• Pallet information. If pallet information is not included, LTL transportation options aren't generated.

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

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 the cost, a void window (for example, duration where a seller can cancel a shipment and receive a refund for their transportation quote), and expiration for each quote. 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 can 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, before using an Amazon-partnered carrier for an inbound shipment, 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.

Review the available delivery window options for each shipment within an inbound plan using the listDeliveryWindowOptions operation. To make this call, a seller needs to pass the shipmentID. A successful response provides the startDate and endDate for each available delivery window and the level of congestion (availabilityType) for each option. Note that 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.

Review the 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:

• Placement option ID
• Shipment confirmed ID (that is, the ID that shows up on labels)
• Shipment ID (that is, 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

Step 6. Select transportation options

❗️

Important

For non-partnered carrier shipments, sellers must confirm their anticipated delivery window by calling confirmTransportationOptions before they book their fulfillment center (FC) appointment.

Sellers should ask their non-partnered carrier to book an FC appointment that is within their anticipated delivery window. If the FC appointment date does not fall within the delivery window, the seller can call confirmDeliveryWindow to select another delivery window that does contain their FC appointment date.

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 ship the inbound shipment. Prior to this call, a seller must have confirmed a placement option for their inbound plan. To call confirmTransportationOptions, a seller must pass the shipment ID, selected transportation option ID, contact information (needed for partnered carriers for LTL shipments), and estimated delivery date. The estimated delivery date (delivery window) is a requirement for non-partnered carrier options and should not be populated for partnered carrier options. After a transportation option is been confirmed, new transportation options cannot be generated or confirmed for an inbound plan.

Cancel a shipment

If a seller confirms the transportation request, then decides they don't want the Amazon-partnered carrier to ship the inbound shipment, you can call 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.

Step 7. Print 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.

Information included on shipping labels

In all circumstances, the getLabels operation returns shipping labels that include a unique bar code and Package ID (the string located directly under the bar code). Depending on the contents of the packages in your shipments, the labels can also include an ASIN and an expiration date.

Shipping labels include an ASIN and an expiration date in either of the following situations:

• Every item in the shipment shares the same ASIN and expiration date.
• The shipment includes multiple ASINs, but every package in the shipment contains items that share the same ASIN and expiration date.

Shipping labels include an ASIN and no expiration date in either of the following situations:

• Every item in the shipment shares the same ASIN. The ASIN does not have an expiration date.
• The shipment includes multiple ASINs, but every package in the shipment contains items that share the same ASIN. The ASINs do not have expiration dates.

Shipping labels do not include an ASIN or an expiration date when the shipment contains at least one package with items that do not share the same ASIN and expiration date.

📘

Construct a unique barcode for small parcel shipments

For Small Parcel shipments, the shipping label for each package should have a unique barcode. This helps ensure that your shipment is processed in a timely manner when it reaches Amazon's fulfillment network. To construct unique barcode values for each package in a shipment, do the following:

1. Start with the Shipment ID value and append U and 000001 to get the barcode value for the first package in the shipment.

2. To get the barcode values for each successive package in the shipment, increment the trailing numerical value of the previous package by one. For example, If you have three packages in a shipment with a Shipment ID value of FBA1MMD8D0, your three barcode values would be FBA1MMD8D0U000001, FBA1MMD8D0U000002, and FBA1MMD8D0U000003. A box label identified with its own unique numerical identifier must follow the 6-digit number format after U, printed and affixed to each carton you send to a fulfillment center (for example, U000001, U000002, U000003).

Step 8. 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.

Step 9. 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.