HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Additional Functionality

Additional Functionality of the Fulfillment Inbound API

The Fulfillment Inbound API v2024-03-20 also includes several operations that are not mandatory for every shipment creation. This section describes these operations.

Retrieve a list of existing inbound plans

Retrieve a list of existing inbound plans by using the listInboundPlans operation. This can be used to retrieve inbound plan information for multiple inbound plans based on criteria that the seller specifies. By calling the listInboundPlans operation, a seller can filter by state (for example, whether the InboundPlans are ACTIVE, SHIPPED, or VOIDED) and by the date that the inbound plan was created or last updated. The seller can also indicate a page size to limit the responses per request and a pagination token if needed.

🚧

Important

listInboundPlans is a paginated call. When you make follow-up calls to get more pages of data, you must pass the same filters as you did in the original call to get the correct response.

Retrieve a list of items in an inbound plan

Retrieve a list of items within an inbound plan with the listInboundPlanItems operation. This can be used to retrieve item information for an inbound and can be filtered by package grouping ID (that is, the ShipmentID or the PackingGroupId, depending on whether confirmPlacementOption has been called).

A successful response includes item information such as MSKU, ASIN, FNSKU, label owner, quantity, expiration date, manufacturing lot code, prep instructions, and packing group.

Retrieve a list of pallets associated with inbound plans

Retrieve a list of pallets within an inbound plan with the listInboundPlanPallets operation. This can be used to retrieve pallet information for an inbound plan and can be filtered by package grouping ID (that is, the ShipmentID or the PackingGroupId, depending on whether confirmPlacementOption has been called).

A successful response includes pallet dimensions, weight, whether the pallets can be stacked, package ID, pallet quantities, and associated shipment IDs.

Cancel an Inbound Plan

Cancel an inbound plan and all of the associated shipments by using the cancelInboundPlan operation. This also cancels the fees associated with the transportation options selected by the seller, if this operation is called within the void window. The void window is 24 hours after you confirm a Small Parcel shipment transportation request or one hour after you confirm a Less Than Truckload / Full Truckload (LTL/FTL) shipment transportation request. After this deadline passes, the seller's account is charged for the shipping cost.

A successful response includes the operationId that can be used to determine the status of the operation using getInboundOperationStatus. Alternatively, a seller can confirm that their inbound plan has been voided by retrieving its status by calling getInboundPlan.

Update shipment name

Update the name of a shipment using the updateShipmentName operation. The user might want to use this to link the shipment ID from the given identifier with a string provided by the user. The shipment ID is preserved after updating this name, and is used to identify the shipment using other operations. To update a shipment name, pass the new name as a string per the request body schema.

A successful response provides an operationID that you can use to check the status of the corresponding operation with getInboundOperationStatus. The name can be used to find and navigate shipments.

Update inbound plan name

Update the name of an existing inbound plan using the updateInboundPlanName operation. The user might want to use this to link the shipment ID from the given identifier with a string provided by the user. To update an inbound plan name, post the new name as a string per the request body schema.

A successful response gives you an operation ID you can use to check the status of the corresponding operation with getInboundOperationStatus. The name can be used to find and navigate inbound plans.

List shipment pallets

View a paginated list of pallets associated with a shipment by calling the listShipmentPallets operation. An inbound plan contains pallet information after the user has provided the pallet details while generating Less Than Truckload (LTL) carrier shipments using the generateTransportationOptions operation.

A successful response contains a paginated list of the previously input pallets and their weights, dimensions, and stackability. The response also contains an identifier for the pallet, which can be used to match a pallet with its labels.

List shipment boxes

View a paginated list of box packages in a shipment by calling the listShipmentBoxes operation. Shipping boxes must first be generated with the setPackingInformation operation before becoming available.

A successful response includes information about the boxes in the shipment and the items in the boxes. Each box has a corresponding package ID which can be used to match box labels to boxes. The response also includes details about each box such as its weight / dimensions and what items are inside each box. The response includes the following for each item:

  • MSKU
  • ASIN
  • FNSKU
  • Manufacturer lot code
  • Label owner
  • Prep instruction
  • Prep type
  • Prep owner

If the items have expiration dates, those are included in the response. This API gives a detailed list of information that users need to create a pack list that can be used to help ensure the shipment is complete before sending to the fulfillment centers.

Create marketplace item labels

The createMarketplaceItemLabels operation provides labels for a list of MSKUs for a given marketplace. Using this operation you can get item labels in the marketplace language. This is useful for dynamic sellers who operate in multiple marketplaces, and allows you to easily identify which items are planned for which markets.

List shipment items

View a paginated list of items in a shipment by calling the listShipmentItems operation. Sellers need this information to learn which items are in each shipment split if they didn't input the carton-level information.

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 also lists the product’s MSKU, ASIN, FNSKU, Manufacturer Code, quantity, and expiration date if needed. This can be used to generate a pick list that 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 of which items go in which boxes.

Retrieve preparation instructions for an MSKU

Call the listPrepDetails operation to retrieve preparation instructions for shipping an MSKU into Amazon’s fulfillment network in a specific marketplace.

You can use listPrepDetails to determine which prepOwner and labelOwner values can be used in the createInboundPlan operation. Appropriate prepOwner values are returned in prepOwnerConstraint and appropriate labelOwner values are returned in labelOwnersConstraint. If these fields are empty in the response, you can select AMAZON or SELLER. If allOwnersConstraint is MUST_MATCH, prepOwner and labelOwner must match. If allOwnerConstraint is empty, then prepOwner and labelOwner do not need to match.

🚧

Warning

Inventory that arrives at a fulfillment center without proper preparation or labeling might incur a preparation fee. For more information, refer to Unplanned services. A unit that falls under multiple categories must be prepped according to all applicable prep types. For example, if you sell bottles of shampoo and conditioner as a set, both units must meet the prep requirements for liquid products and be labeled with a "Sold as set" sticker so they are not separated.

You can also use this operation to retrieve the current prepCategory and prepTypes for an MSKU (if they are already set), which indicates how each MSKU must be prepared. If prepCategory is FC_PROVIDED, then Amazon has established a prepCategory for this MSKU and it cannot be changed. For information about preparing items for shipment, refer to the Seller Central help page for your marketplace.

📘

Note

If you observe a discrepancy in the prep category returned by this operation and what is displayed on Send to Amazon, refresh the Send to Amazon page to ensure that the correct prep category is shown.

Set preparation instructions for an MSKU

Call the setPrepDetails operation to provide information related to how an MSKU is prepared for shipment. Sellers must provide this information once for each MSKU in a marketplace. Amazon saves this information for future shipments that include this MSKU. The prepCategory you select using this operation can affect what values you can select for prep and label owners, which are required inputs for createInboundPlan. Use the listPrepDetails operation to retrieve the available prep and label owners.

🚧

Caution

If PrepType is ITEM_NO_PREP, you may still need to include a prep owner or label owner when you call createInboundPlan. If prepCategory is NONE, you might need to include a label owner in createInboundPlan. In both situations, you can identify the list of available prep and label owners with the listPrepDetails operation.

When you call setPrepDetails, you must pass the prepCategory and prepTypes for each MSKU and marketplace ID. For more information about the relationship between prep category and prep types, refer to Prep guidance. For information about preparing items for shipment, refer to the Seller Central help page for your marketplace.

🚧

Caution

If you change the prepCategory for an MSKU after you use createInboundPlan to create a plan that includes this MSKU, use the prepOwner and labelOwner that are associated with that plan as the setPackingInformation value for that inbound plan. You can get prepOwner and labelOwner by using listInboundPlanItems or listInboundPlanBoxes. The prepCategory information that you updated by using setPrepDetails carries over to subsequent inbound plans.

Update information in a shipment

Update the contents of an existing shipment with the following operations:

These operations help sellers update the quantity of their shipments, add and remove boxes, and remove SKUs before Amazon receives them.

You can only call these operations after you confirm transportation options and before the shipment is in Receiving status. Before the shipment arrives at the fulfillment center, you can edit the number of units in a shipment by up to five percent or six units per SKU per shipment, whichever is greater. You can also remove a SKU from a shipment, as long as the original quantity is six units or fewer per SKU per shipment. You can’t remove all SKUs in a shipment or make a shipment empty. To make changes beyond these limits, you must cancel the inbound plan and create a new one.

Step 1. Update the contents of the shipment

To update the contents of a shipment, call the generateShipmentContentUpdatePreviews operation and pass the boxes and items that will be present in the shipment after the update. A successful response contains the inboundPlanID and the operationId, which you can use to retrieve the request status.

Step 2. Review the changes and quotes

Next, review the proposed changes and updated transportation quotes with listShipmentContentUpdatePreview.

Step 3. Confirm updates

Confirm the updates to the shipment with confirmShipmentContentUpdatePreview. Call this operation with the following values from the listShipmentContentUpdatePreview response:

  • inboundPlanID
  • shipmentID
  • contentUpdatePreviewId

Prerequisite step. Create a listing and convert it to FBA

If a product already exists in the Amazon catalog, you can create a listing by associating a unique seller-defined SKU with the unique Amazon-defined ASIN (Amazon Standard Item Number) for the product.

If a product does not exist in the Amazon catalog, to create a listing you must provide descriptive information about the product so Amazon can build a record and assign an ASIN to the product. You can create listings with the Listings Items API or the Feeds API.

❗️

Important

Before you can convert a listing to FBA, you must provide additional information on any products that are batteries, contain or are sold with batteries, or might be considered dangerous goods. Any attempt to convert a listing to FBA without providing battery and dangerous goods information will fail. For more information, refer to FBA product restrictions.

Create a listing with the Listings Items API

If the product already exists in the Amazon catalog, refer to List an item that already exists in the Amazon catalog.

If the product does not exist in the Amazon catalog, refer to List an item that does not already exist in the Amazon catalog.

In both cases, list the items with the fulfillment availability as follows:

"fulfillment_availability": [
  {
    "fulfillment_channel_code": "AMAZON_NA"
  }
]

Set fulfillment_channel_code to AMAZON_NA, AMAZON_EU, AMAZON_IN, or AMAZON_JP, depending on the seller's marketplace.

Create a listing with the Feeds API

Bulk submissions are optimal for processing 1500 items or more. Refer to Create and update listings items in bulk.

Convert Fulfilled by Merchant (FBM) to Fulfilled by Amazon (FBA)

If you already have an existing listing with FBM, you can convert it to FBA with the Listings Items API or the Feeds API:

To use the Listings Items API, call the patchListingsItem operation:

PATCH https://sellingpartnerapi-na.amazon.com/listings/2021-08-01/items/AXXXXXXXXXXXXX/ABC123
	?marketplaceIds=ATVPDKIKX0DER
	&issueLocale=en_US
{
  "productType": "PRODUCT",
  "patches": [
    {
      "op": "add",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "AMAZON_NA" // as per region
        }
      ]
    },
    {
      "op": "delete",
      "path": "/attributes/fulfillment_availability",
      "value": [
        {
          "fulfillment_channel_code": "DEFAULT"
        }
      ]
    }
  ]
}

To use the Feeds API, call the createFeed operation with the JSON_LISTINGS_FEED:

{
  "header": {
    "sellerId": "xxxxxxxxxx",
    "version": "2.0",
    "issueLocale": "en_US"
  },
  "messages": [
    {
      "messageId": 1,
      "sku": "xx-xxx-xxxx",
      "operationType": "PATCH",
      "productType": "PRODUCT",
      "patches": [
        {
          "op": "add",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "AMAZON_NA" // as per region
            }
          ]
        },
        {
          "op": "delete",
          "path": "/attributes/fulfillment_availability",
          "value": [
            {
              "fulfillment_channel_code": "DEFAULT"
            }
          ]
        }
      ]
    }
  ]
}

Set fulfillment_channel_code to AMAZON_NA, AMAZON_EU, AMAZON_IN, or AMAZON_JP, depending on the seller's marketplace.

Updated 2 days ago