HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Fulfillment Outbound API v2020-07-01 Use Case Guide

How to use the Fulfillment Outbound API.

The Selling Partner API for Fulfillment Outbound (Fulfillment Outbound API) lets you create applications that help a seller fulfill Multi-Channel Fulfillment orders using their inventory in Amazon's fulfillment network. You can also get information on both potential and existing fulfillment orders.

Tutorial: Retrieve proof of delivery for a delivered package

Learn how to get the photo or signature for a delivered Multi-Channel Fulfillment Outbound shipment.

Prerequisites

To complete this tutorial, you need:

Get proof of delivery

Call the getFulfillmentOrder operation.

Tutorial: Retrieve a list of fulfillment orders

This tutorial shows you how to get a list of fulfillment orders after (or at) a specific date-time, or indicated by the next token parameter.

Prerequisites

To complete this tutorial, you need:

Get a list of all fulfillment orders

Call the listAllFulfillmentOrders operation.

Tutorial: Retrieve delivery tracking information

This tutorial shows you how to get delivery tracking information for a package in an outbound shipment for a Multi-Channel Fulfillment order.

Prerequisites

To complete this tutorial, you need:

Get the package tracking details

Call the getPackageTrackingDetails operation.

Tutorial: Cancel a fulfillment order

This tutorial shows you how to send a request to Amazon to stop attempts to fulfill a fulfillment order indicated by the specified order identifier for a given marketplace. The cancelFulfillmentOrder operation should only be called when the order is in 'Received' or 'Planning' status.

Prerequisites

To complete this tutorial, you need:

Cancel a fulfillment order

Call the cancelFulfillmentOrder operation.

Tutorial: Retrieve a list of features

This tutorial shows you how to get a list of features available for Multi-Channel Fulfillment orders in the marketplace you specify, and whether the seller for which you made the call is enrolled for each feature.

Prerequisites

To complete this tutorial, you need:

Get a list of features

Call the getFeatures operation.

Tutorial: Retrieve inventory eligible for Blank Box

This tutorial shows you how to get a list of inventory items that are eligible for Blank Box.

Prerequisites

To complete this tutorial, you need:

Get a list of feature inventory items

Call the getFeatureInventory operation.

Tutorial: Retrieve Blank Box inventory for a specific SKU

This tutorial shows you how to get the total number of feature seller SKUs with the sellerSKU you specify.

📘

Ineligible sellerSKU

If the sellerSKU isn't eligible, the response contains an empty skuInfo object.

Prerequisites

To complete this tutorial, you need:

Get a count of feature Seller SKUs

Call the getFeatureSKU operation.

Tutorial: Create a Japan order with scheduled delivery and delivery time windows

This tutorial outlines the order creation process for Japan with the scheduled delivery shipping option. This ship option is only available for Japan marketplace orders.

Prerequisites

To complete this tutorial, you need:

Step 1. Get the fulfillment preview for scheduled delivery dates

Call the getFulfillmentPreview operation. Set shippingSpeedCategories equal to ScheduledDelivery and includeDeliveryWindows equal to true.

Request example

POST "https://sellingpartnerapi-fe.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview"
{
  "marketplaceId": "A1VC38T7YXB528",
  "address": {
    "name": "Mary Major",
    "addressLine1": "1-8-1 Shimomeguro",
    "addressLine2": "Meguro-ku",
    "city": "Tokyo",
    "countryCode": "JP",
    "postalCode": "153-0064"
  },
  "items": [
    {
      "sellerSku": "SellerSKU12",
      "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
      "quantity": 2
    }
  ],
  "shippingSpeedCategories": [
    "ScheduledDelivery"
  ],
  "includeDeliveryWindows": "true"
}

Step 2. Create a fulfillment order

Call the createFulfillmentOrder operation with the Delivery Window obtained from the getFulfillmentPreview response and with shippingSpeedCategory set to ScheduledDelivery. If you use any other window with the createFulfillmentOrder operation, the service returns an error and you must call getFulfillmentPreview again.

📘

Note

Shipping method service-level agreements vary by marketplace. Sellers can refer to Seller Central for shipping method service-level agreements and multi-channel fulfillment fees.

Step 3. Get the fulfillment order to validate order details

After successfully calling the createFulfillmentOrder operation, call the getFulfillmentOrder operation to validate that the fulfillmentAction value is equal to Ship and fulfillmentOrderStatus is equal to Received.

Response example

{
  "payload": {
    "fulfillmentOrder": {
      "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
      "marketplaceId": "A1VC38T7YXB528",
      "displayableOrderId": "CONSUMER-2022921-145045",
      "displayableOrderDate": "2022-01-09T19:46:45.809Z",
      "displayableOrderComment": "TestOrder",
      "shippingSpeedCategory": "ScheduledDelivery",
      "destinationAddress": {
        "name": "Mary Major",
        "addressLine1": "1-8-1 Shimomeguro",
        "addressLine2": "Meguro-ku",
        "city": "Tokyo",
        "countryCode": "JP",
        "postalCode": "153-0064"
      },
      "deliveryWindow": {
        "endDate": "2022-12-15T10:48:11Z",
        "startDate": "2022-12-15T06:48:11Z"
      }
      "fulfillmentAction": "Ship",
      "fulfillmentPolicy": "FillAllAvailable",
      "receivedDate": "2022-09-21T14:50:45Z",
      "fulfillmentOrderStatus": "Received",
      "statusUpdatedDate": "2022-09-22T03:44:35Z"
    },
    "fulfillmentOrderItems": [
      {
        "sellerSku": "SellerSKU12",
        "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
        "quantity": "1"
      }
    ],
    "fulfillmentShipments": [],
    "returnItems": [],
    "returnAuthorizations": []
  }
}

Tutorial: Create an MCF order for India

This tutorial outlines the MCF order creation process for India.

Prerequisites

To complete this tutorial, you need:

Step 1. Get a fulfillment preview

Call the getFulfillmentPreview operation.

Step 2a. Create a fulfillment order

Call the createFulfillmentOrder operation to create an MCF order specifying the feature constraints required for the order.

Step 2b. Create a fulfillment order with a COD option

Call the createFulfillmentOrder operation to create an MCF order with a cash on delivery (COD) option. For COD orders in the IN marketplace, none of the monetary values in codSettings (codCharge, codChargeTax, shippingCharge, shippingChargeTax) should be set. All the charges in the order must be represented with perUnitDeclaredValue in the items array.

Step 3. Get the fulfillment order to validate order details

After successfully calling the createFulfillmentOrder operation, call the getFulfillmentOrder operation to validate the fulfillmentAction is equal to Ship and fulfillmentOrderStatus is equal to Received.

Tutorial: Track a partially fulfilled order

This tutorial walks you through the steps on how to track a partially fulfilled order for items that are low inventory.

Prerequisites

To complete this tutorial, you need:

Step 1. Get a fulfillment preview

Call the getFulfillmentPreview operation with two line items and make sure they are available for a given shipping option (Standard, Expedited, or Priority).

An unsuccessful response has a non-2xx code and includes the following objects. If the PackageNumber does not exist, a 404 response provides the ineligibility errors.

Step 2. Create an MCF outbound order

Call the createFulfillmentOrder operation with a unique Order ID and at least two line items, or one line item with a quantity greater than 1 for the same shipping option.

Step 3. Validate the order details

Call the getFulfillmentOrder operation to validate that fulfillmentAction is equal to Ship and fulfillmentOrderStatus is equal to Received.

Step 4. Order status changes

The order goes through status changes from Planning to Processing to Complete, in case one or more items do not have enough inventory as requested in the createFulfillmentOrder operation. To get status change updates, subscribe and listen to FULFILLMENT_ORDER_STATUS notifications.

Step 5. Get the fulfillment order to view the latest order details

After the order is Shipped, the order status notification for Complete is triggered. Now call the getFulfillmentOrder operation to view the latest order details.

Step 6. Validate the order status and line item quantities

Validate that fulfillmentShipmentStatus is equal to Shipped and fulfillmentOrderStatus is equal to CompletePartialled. If there are items that have unfulfillableQuantity not equal to 0, then the order is partially fulfilled.

Step 7. Get the package number

Copy the package number of the order from the getFulfillmentOrder response from Step 5. There could be multiple package numbers based on the number of Amazon shipments for that order.

Step 8. Get the tracking details

Call the getPackageTrackingDetails operation using the package number from Step 7 and get the complete tracking details of the package.

An unsuccessful response has a non-2xx code and includes the following objects. If the PackageNumber does not exist, a 404 response provides the ineligibility errors.

Tutorial: Create an order in hold status and then move it to shipped

This tutorial explains how an order can move from a fulfillment status of HOLD to SHIP. Orders in HOLD status do not proceed to further fulfillment actions until the status is updated to SHIP.

Prerequisites

To complete this tutorial, you need:

Step 1. Get the fulfillment preview

Call the getFulfillmentPreview operation on the order to ensure the SKUs are eligible and fulfillable for the requested ship options (Standard, Expedited, Priority).

An unsuccessful response has a non-2xx code and includes the following objects. A 404 response provides the ineligibility errors, if any.

Step 2. Create a fulfillment order on hold

Call the createFulfillmentOrder operation with one or more line items with fulfillmentAction set equal to Hold. Doing so keeps the order in Hold status and further fulfillment actions don't run on that order.

Step 3. Update the order fulfillment action to ship

Call the updateFulfillmentOrder operation to update the order with fulfillmentAction equal to Ship to move the order from Hold to Ship.

Request example

PUT "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"
{
  "fulfillmentAction": "Ship"
}

Step 4. Get the fulfillment order to validate the changes

On the successful update of the order, call the getFulfillmentOrder operation to validate that fulfillmentAction is updated to Ship. After the order moves to the Ship action, the next fulfillment steps start running on the order.

Tutorial: Track an order with an item's serial number

For select products, a seller might need to know which instance of an item was sold to a particular customer. If the items are uniquely tracked with a serial number, the fulfillment centers can add steps to scan and record the serial numbers both going out and being returned.

After an item is shipped out, the getFulfillmentOrder operation has the serial number in the response for the seller to keep a record of it.

Prerequisites

  • The seller needs to share the Regex of the generated serial numbers with Amazon.
  • The seller needs to paste the generated unique serial number on every item when inbounding the inventory to Amazon.
  • If the customer is using the Amazon Labeling Service, in addition to registering an ASIN, the FNSKU associated with the item must also be registered using the same process.
  • Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
  • The Amazon Fulfillment role assigned to your developer profile.
  • The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Create a fulfillment order with serial numbered items

Call the createFulfillmentOrder operation to create an MCF order with line items that have serial numbers enabled while inbounding to Amazon. The createFulfillmentOrder request doesn't need any exclusive attributes in the request for this type of order.

Step 2. Get the fulfillment order to validate the order details

After successfully creating the order, call the getFulfillmentOrder operation to validate that fulfillmentAction is equal to Ship and fulfillmentOrderStatus is equal to Received on the order.

Step 3. Get the fulfillment order to track status changes

The order goes through status changes, from Planning to Processing to Complete. Subscribe and listen to FULFILLMENT_ORDER_STATUS notifications to be aware of these status changes. When the order is shipped, the serial number of the item is scanned and validated to match the shared regex.

Call the getFulfillmentOrder operation with the sellerFulfillmentOrderId to view the latest order details and check if the serial number of the item was shipped.

Step 4. Validate the order status and line item quantities

Validate that fulfillmentShipmentStatus is equal to Shipped and that the serialNumber in fulfillmentShipmentItem is the same as what was generated during the inbound process.

Tutorial: Create an order with cross border fulfillment

This tutorial outlines how a seller who operates and sells in two different countries can fulfill orders across the border. This operation only works for books, videos, media and discs products.

In this example, the seller is trying to fulfill an order from a Canadian (CA) warehouse to a US address.

Prerequisites

To complete this tutorial, you need:

Step 1. Create a Fulfillment order for cross border shipment

Create an order with a US destination address and shipFromCountryCode=CA. In this case, we can skip specifying the marketplaceId in the request and the item is picked from the CA marketplace. Also, include perUnitDeclaredValue in the items of value greater than 0. Call the createFulfillmentOrder operation.

Request example

POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders"

{
  "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
  "displayableOrderId": "CONSUMER-2022921-145045",
  "displayableOrderDate": "2022-01-09T19:46:45.809Z",
  "displayableOrderComment": "TestOrder",
  "shippingSpeedCategory": "Standard",
  "fulfillmentAction": "Ship",
  "shipFromCountryCode": "CA",
  "destinationAddress": {
    "name": "Mary Major",
    "addressLine1": "Stockton Street",
    "city": "Alexandria",
    "stateOrRegion": "VA",
    "countryCode": "US",
    "postalCode": "22308"
  },
  "items": [
    {
      "sellerSku": "LT205BLKAM",
      "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
      "quantity": 1,
      "perUnitDeclaredValue": {
        "currencyCode": "USD",
        "value": "0.10"
      }
    }
  ]
}

Tutorial: Create orders with Blank Box and Block AMZL features requested

When creating an order, MCF offers two features which can be specified in the request:

  • Blank Box: Allows the seller to choose boxing with no Amazon logos/labels on it.
  • Block AMZL: Allows the seller to refuse Amazon logistics and rather ship out using another carrier service.

After the request is made during the create order process, it cannot be updated during the fulfillment steps of the order.

Prerequisites

To complete this tutorial, you need:

Step 1. Get a fulfillment preview for given feature constraints

Call the getFulfillmentPreview operation on the line items of the order using a given ship option and feature constraint to ensure that the features are available for order fulfillment for the marketplace and address.

Step 2. Create a fulfillment order specifying the feature constraints

Call the createFulfillmentOrder operation to create an MCF order specifying the feature constraints required for the order.

📘

Feature constraints

Feature constraints can be enabled in the Seller Central portal which acts as a default value, but the value specified in the order request takes priority.

Step 3. Get the fulfillment order to validate order details

After successfully creating an order, call the getFulfillmentOrder operation to validate that fulfillmentAction is equal to Ship, fulfillmentOrderStatus is equal to Received, and featureConstraints are returned in the order details response.

Tutorial: Show the preview details of all ship speeds

If the getFulfillmentPreview operation is called without mentioning any ship speeds in the request, the response shows preview details of all ship speeds.

Prerequisites

To complete this tutorial, you need:

Step 1. Get the fulfillment preview for all ship speeds

To retrieve preview details of an order for all ship speeds, do not include the shippingCategories attribute in the request.

Call the getFulfillmentPreview operation.

Tutorial: View order notifications with the Notifications API

A seller can subscribe to FULFILLMENT_ORDER_STATUS notifications to be aware of all the changes happening on the order.

To complete this tutorial, you need:

Prerequisites

Step 1. Create and subscribe to notifications

Use the createSubscription operation of the Notifications API to subscribe to the FULFILLMENT_ORDER_STATUS notification.

Step 2. Listen to order status notifications

The FULFILLMENT_ORDER_STATUS notification keeps the seller posted on changes to the order status.

Review the FulfillmentShipmentPackages array in the response to get the package details of an order when it’s made ready for shipping.

Tutorial: Create a return for an MCF order

MCF order returns are comprised of three steps:

  1. Getting the return reason codes
  2. Submitting the return using one of the codes
  3. Returning the object

Currently, MCF expects the end customer to pay for the postage charges as the return labels shared are not prepaid.

Prerequisites

To complete this tutorial, you need:

Step 1. Get a list of return reason codes for a given product

Call the listReturnReasonCodes operation.

Step 2. Create a fulfillment return for an order

Using one of the reasons retrieved in the previous step, call the createFulfillmentReturn operation to submit the return request and retrieve the return shipping label needed to ship the item to Amazon.

📘

Note

This label is not prepaid. It must be paid by the shipper.

Step 3. Ship the returning item

From the previous response, the rmaPageURL provides the return label which needs to be printed and pasted on the package and the postage charges need to be paid by the returning shopper.

Step 4. Get the fulfillment order to validate the order return

After the package is received by the Amazon warehouse, the item is marked returned for that order. Call the getFulfillmentOrder operation to validate that the return authorization is populated on the original order. returnItems and returnAuthorizations should populate the same details as the createFulfillmentReturn response along with the status/condition of the item returned.

Tutorial: Get dynamic delivery offers

This tutorial outlines how to get dynamic delivery offers for a buyable product using a US ZIP Code or US IP address.

Prerequisites

To complete this tutorial, you need:

Step 1. Get a dynamic delivery offer

Call the deliveryOffers operation to get the dynamic delivery offer for standard click-to-delivery speed for the specified product and location information.

If a delivery offer isn't available, the deliveryOffers array is empty in the response.

Tutorial: Create a Japan order with delivery preferences

This tutorial outlines the order creation process for Japan with delivery preferences. This feature is only available for Japan marketplace orders.

Prerequisites

To complete this tutorial, you need:

Step 1. Create a fulfillment order specifying the delivery preferences

Call the createFulfillmentOrder operation to create an MCF order specifying the delivery preferences required for the order.

Tutorial: Create a Japan order providing neighbor details in delivery preferences

This tutorial outlines the order creation process for Japan where the delivery preference is set to a designated neighbor if the recipient is not available at the destination address. This feature is only available for Japan marketplace orders.

Prerequisites

To complete this tutorial, you need:

Step 1. Create a fulfillment order specifying the delivery preferences

Call the createFulfillmentOrder operation to create an MCF order specifying the delivery preferences required for the order.

Tutorial: Retrieve locker (delivery box) details for packages delivered in Japan

This tutorial shows you how to get locker information for a package that was delivered to a locker (delivery box) for Japan in an outbound shipment for a Multi-Channel Fulfillment order.

The getFulfillmentOrder operation might not always return lockerDetails, depending on the delivery status and delivery location.

Use the getPackageTrackingDetails operation to check the delivery status and identify if the package was delivered to a locker (delivery box).

Prerequisites

To complete this tutorial, you need:

Step 1. Get the fulfillment order to view the latest order details and locker details if present

Call the getFulfillmentOrder operation.

Updated 8 days ago

OSZAR »