Fulfillment Outbound API v2020-07-01 Use Case Guide

Fulfillment Outbound API Use Case Guide

API Version: v2020-07-01

What is 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.

Prerequisites

All the tutorials require the following:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.

  2. The Amazon Fulfillment role assigned to your developer profile.

  3. The Amazon Fulfillment role selected in the App registration page for your application.

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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.

  2. The Amazon Fulfillment role assigned to your developer profile.

  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Get a list of all fulfillment orders

Call the listAllFulfillmentOrders operation by passing the following parameters:

ParameterDescriptionRequired
queryStartDate

A date used to select fulfillment orders that were last updated after (or at) a specified time. An update is defined as any change in fulfillment order status, including the creation of a new fulfillment order.

Type: string (date-time)

no
nextToken

A string token returned in the response to your previous request. It is required for fetching the next set of results [pagination]

Type: string

no

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders?queryStartDate=2020-01-01T19:46:45Z"

Response

A successful response has a code of 200.

Response example

{
  "payload": {
    "fulfillmentOrders": [
      {
        "sellerFulfillmentOrderId": "902-6018020-0202003",
        "displayableOrderId": "mws-test-query-20100713023203751",
        "displayableOrderDate": "2020-01-09T19:46:45Z",
        "displayableOrderComment": "TestOrder",
        "shippingSpeedCategory": "Standard",
        "destinationAddress": {
          "name": "AnyCompany",
          "addressLine1": "123 Any Street",
          "addressLine2": "Suite 123",
          "city": "Any Town",
          "stateOrRegion": "MI",
          "countryCode": "US",
          "postalCode": "48084"
        },
        "fulfillmentPolicy": "FillOrKill",
        "receivedDate": "2020-01-21T21:07:13Z",
        "fulfillmentOrderStatus": "RECEIVED",
        "statusUpdatedDate": "2020-01-21T21:07:30Z",
        "featureConstraints": [
          {
            "featureName": "BLANK_BOX",
            "featureFulfillmentPolicy": "NotRequired"
          },
          {
            "featureName": "BLOCK_AMZL",
            "featureFulfillmentPolicy": "NotRequired"
          }
        ]
      },
      {
        "sellerFulfillmentOrderId": "601-2020200-12345678",
        "displayableOrderId": "TestOrder-FBAOutbound",
        "displayableOrderDate": "2020-01-09T19:46:45Z",
        "displayableOrderComment": "TestOrder",
        "shippingSpeedCategory": "Standard",
        "destinationAddress": {
          "name": "AnyCompany",
          "addressLine1": "123 Any Street",
          "addressLine2": "Suite 123",
          "addressLine3": "Lane1",
          "city": "Any Town",
          "stateOrRegion": "MI",
          "countryCode": "US",
          "postalCode": "48084"
        },
        "fulfillmentPolicy": "FillOrKill",
        "receivedDate": "2020-01-23T19:56:41Z",
        "fulfillmentOrderStatus": "COMPLETE",
        "statusUpdatedDate": "2020-01-24T15:28:27Z",
        "featureConstraints": [
          {
            "featureName": "BLANK_BOX",
            "featureFulfillmentPolicy": "NotRequired"
          },
          {
            "featureName": "BLOCK_AMZL",
            "featureFulfillmentPolicy": "Required"
          }
        ]
      }
    ]
  }
}
NameDescriptionRequired
sellerFulfillmentOrderId

The fulfillment order identifier submitted with the createFulfillmentOrder operation.

Type: string

Yes
marketplaceId

The identifier for the marketplace the fulfillment order is placed against.

Type: string

Yes
displayableOrderId

A fulfillment order identifier submitted with the createFulfillmentOrder operation. Displays as the order identifier in recipient-facing materials such as the packing slip.

Type: string

Yes
displayableOrderDate

A date and time submitted with the createFulfillmentOrder operation. Displays as the order date in recipient-facing materials such as the packing slip.

Type: Timestamp

Yes
displayableOrderComment

A text block submitted with the createFulfillmentOrder operation. Displays in recipient-facing materials such as the packing slip.

Type: string

Yes
shippingSpeedCategory

The shipping method used for the fulfillment order.

Type: ShippingSpeedCategory

Yes
deliveryWindow

The time range within which a Scheduled Delivery fulfillment order should be delivered.

Type: DeliveryWindow

No
destinationAddress

The destination address submitted with the createFulfillmentOrder operation.

Type: Address

Yes
fulfillmentAction

Specifies whether the fulfillment order should ship now or have an order hold put on it.

Type: FulfillmentAction

No
fulfillmentPolicy

The FulfillmentPolicy value specified when you submitted the createFulfillmentOrder operation.

Type: FulfillmentPolicy

No
codSettings

The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

Type: CODSettings

No
receivedDate

The date and time that the fulfillment order was received by an Amazon fulfillment center.

Type: Timestamp

Yes
fulfillmentOrderStatus

The current status of the fulfillment order.

Type: FulfillmentOrderStatus

Yes
statusUpdatedDate

The date and time that the status of the fulfillment order last changed, in ISO 8601 date time format.

Type: Timestamp

Yes
notificationEmails

A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

Type: NotificationEmailList

No
featureConstraints

A list of features and their fulfillment policies to apply to the order.

Type: < FeatureSettings > array

No

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the operation.

Type: ErrorList

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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Get the package tracking details

Call the getPackageTrackingDetails operation by passing the following parameters:

ParameterDescriptionRequired
packageNumber

The package identifier returned by the getFulfillmentOrder operation.

Type: integer (int32)

Yes

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/tracking?packageNumber=1987644423"

Response example

{
  "payload": {
    "packageNumber": 1987644423,
    "trackingNumber": "TBA123456789012",
    "carrierCode": "AMZN_US",
    "carrierPhoneNumber": "1111111111",
    "carrierURL": "https://www.swiship.com/track?id=TBA123456789012",
    "shipDate": "2022-11-13T03:18:38Z",
    "estimatedArrivalDate": "2022-11-15T03:18:38Z",
    "shipToAddress": {
      "city": "Troy",
      "state": "MI",
      "country": "US"
    },
    "currentStatus": "DELIVERED",
    "signedForBy": "Richard Roe",
    "additionalLocationInfo": "FRONT_DOOR",
    "trackingEvents": [
      {
        "eventDate": "2022-11-13T03:18:37Z",
        "eventAddress": {
          "city": "Buffalo",
          "state": "NY",
          "country": "US"
        },
        "eventCode": "EVENT_101",
        "eventDescription": "Carrier notified to pick up package."
      },
      {
        "eventDate": "2022-11-13T03:18:38Z",
        "eventAddress": {
          "city": "Buffalo",
          "state": "NY",
          "country": "US"
        },
        "eventCode": "EVENT_102",
        "eventDescription": "Shipment picked up from seller's facility."
      },
      {
        "eventDate": "2022-11-13T17:27:49Z",
        "eventAddress": {
          "city": "Boise",
          "state": "ID",
          "country": "US"
        },
        "eventCode": "EVENT_302",
        "eventDescription": "Out for delivery."
      },
      {
        "eventDate": "2022-11-15T03:18:38Z",
        "eventAddress": {
          "city": "Troy",
          "state": "MI",
          "country": "US"
        },
        "eventCode": "EVENT_301",
        "eventDescription": "Delivered."
      }
    ]
  }
}

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

NameDescription
errors

One or more unexpected errors occurred during the getPackageTrackingDetails operation.

Type: ErrorList

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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Cancel a fulfillment order

Call the cancelFulfillmentOrder operation by passing the following parameters:

ParameterDescriptionRequired
sellerFulfillmentOrderId

The identifier assigned to the item by the seller when the fulfillment order was created.

maxLength: 40

Type: string

Yes

Request example

PUT "https://sellingpartnerapi-na.amazon.com /fba/outbound/2020-07-01/fulfillmentOrders/TestOrder-7/cancel"

Response example

{}

An unsuccessful response has a code of non-2xx, and includes the objects below. If the sellerFulfillmentOrderId does not exist, a 404 response will provide the ineligibility errors.

NameDescription
errors

One or more unexpected errors occurred during the cancelFulfillmentOrder operation.

Type: ErrorList

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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Get a list of features

Call the getFeatures operation by passing the following parameters:

ParameterDescriptionRequired
marketplaceId

The marketplace for which to return the list of features.

Type: string

Yes

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/features?MarketplaceId=ATVPDKIKX0DER"

Response

A successful response has a code of 200.

Response example

{
  "features": [
    {
      "featureName": "BLANK_BOX",
      "featureDescription": "Enables Shipment in non-Amazon branded boxes",
      "sellerEligible": true
    },
    {
      "featureName": "BLOCK_AMAZON ",
      "featureDescription": "Blocks using Amazon Logistics as carrier",
      "sellerEligible": true
    }
  ]
}
ParameterDescriptionRequired
featureName

The feature name

Type: string

Yes
featureDescription

The feature description.

Type: string

Yes
sellerEligible

When true, indicates that the seller is eligible to use the feature.

Type: boolean

No

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the getFeatures operation.

Type: ErrorList

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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Get a list of feature inventory items

Call the getFeatureInventory operation by passing the following parameters:

ParameterDescriptionRequired
marketplaceId

The marketplace for which to return a list of the inventory that is eligible for the specified feature.

Type: string

Yes
featureName

The name of the feature for which to return a list of eligible inventory.

Type: string

Yes
nextToken

A string token returned in the response to your previous request that is used to return the next response page. A value of null will return the first page.

Type: string

No

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/features/inventory/BLANK_BOX?marketplaceId=ATVPDKIKX0DER"

Response

A successful response has a code of 200.

Response example

{
  "payload": {
    "marketplaceId": "ATVPDKIKX0DER",
    "featureName": "BLANK_BOX",
    "featureSkus": [
      {
        "sellerSku": "TEST_SKU_BLKAM",
        "fnSku": "X00TEST9UZ",
        "asin": "B08DTESTNM",
        "skuCount": "4",
        "overlappingSkus": []
      },
      {
        "sellerSku": "TEST_SKU_BLKAM2",
        "fnSku": "X00TESTTS5",
        "asin": "B0TESTXXQM",
        "skuCount": "2",
        "overlappingSkus": []
      }
    ]
  }
}

ParameterDescriptionRequired
marketplaceId

The requested marketplace.

Type: string

Yes
featureName

The name of the feature.

Type: string

Yes
nextToken

When present and not empty, pass this string token in the next request to return the next response page.

Type: string

No
featureSkus

An array of SKUs eligible for this feature and the quantity available.

Type: < FeatureSku > array

No

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the getFeatureInventory operation.

Type: ErrorList

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 will contain an empty skuInfo object.

Prerequisites

To complete this tutorial you will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Get a count of feature Seller SKUs

Call the getFeatureSKU operation by passing the following parameters:

ParameterDescriptionRequired
marketplaceId

The marketplace for which to return the count.

Type: string

Yes
featureName

The name of the feature.

Type: string

Yes
sellerSku

Used to identify an item in the given marketplace. SellerSKU is qualified by the seller's SellerId, which is included with every operation that you submit.

Type: string

Yes

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/features/inventory/BLANK_BOX/TEST_SKU_BLKAM?marketplaceId=ATVPDKIKX0DER"

Response example

{
  "payload": {
    "marketplaceId": "ATVPDKIKX0DER",
    "featureName": "BLANK_BOX",
    "isEligible": true,
    "ineligibleReasons": [],
    "sellerSku": "TEST_SKU_BLKAM",
    "fnSku": "X0TEST9UZ",
    "asin": "B0TESTQ6NM",
    "skuCount": "4"
  }
}
ParameterDescriptionRequired
marketplaceId

The requested marketplace.

Type: string

Yes

featureName

The name of the feature.

Type: string

Yes
isEligible

When true, the seller SKU is eligible for the requested feature.

Type: boolean

Yes
ineligibleReasons

A list of one or more reasons that the seller SKU is ineligible for the feature.

Possible values:

  • MERCHANT_NOT_ENROLLED - The merchant isn't enrolled for the feature.

  • SKU_NOT_ELIGIBLE - The SKU doesn't reside in a warehouse that supports the feature.
  • INVALID_SKU - There is an issue with the SKU provided.

Type: < string > array

No
skuInfo

Information about the SKU, including the count available, identifiers, and a list of overlapping SKUs that share the same inventory pool.

Type: FeatureSku

No

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the getFeatureInventory operation.

Type: ErrorList

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

This tutorial will help you understand 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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

Step 1. Get the fulfillment preview for scheduled delivery dates

Call the getFulfillmentPreview operation with values ShippingSpeedCategories = ScheduledDelivery and IncludeDeliveryWindows = true.

Body ParameterDescriptionRequired
marketplaceId

The marketplace the fulfillment order is placed against.

Type: string

No
address

The destination address for the fulfillment order preview.

Type: Address

Yes
items

Identifying information and quantity information for the items in the fulfillment order preview.

Type: GetFulfillmentPreviewItemList

Yes
shippingSpeedCategories

A list of shipping methods used for creating fulfillment order previews.

Possible Values:

  • Standard - Standard shipping method.
  • Expedited - Expedited shipping method.
  • Priority - Priority shipping method.
  • ScheduledDelivery - Scheduled Delivery shipping method only for Japan.

Note: Shipping method service level agreements vary by marketplace. Sellers should see the Seller Central website in their marketplace for shipping method service level agreements and fulfillment fees.

No
includeCODFulfillmentPreview

Specifies whether to return fulfillment order previews that are for COD (Cash On Delivery).

Possible values:

true - Returns all fulfillment order previews (both for COD and not for COD).

false - Returns only fulfillment order previews that are not for COD. Only applicable for orders in Japan.

Type: boolean

No
includeDeliveryWindows

Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The ScheduledDeliveryInfo response object can only be returned for fulfillment order previews with ShippingSpeedCategories = ScheduledDelivery. Only applicable for orders in Japan.

Type: boolean

No
featureConstraints

A list of features and their fulfillment policies to apply to the order.

Type: < FeatureSettings > array

No

Request example

POST "https://sellingpartnerapi-na.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"
  ],
  "includeCodFulfillmentPreview": "true",
  "IncludeDeliveryWindows": "true"
}

Response

A successful response has a code of 200, and the response schema for the getFulfillmentPreview operation.

{
  "payload": {
    "fulfillmentPreviews": [
      {
        "shippingSpeedCategory": "ScheduledDelivery",
        "scheduledDeliveryInfo": {
          "deliveryTimeZone": "string",
          "deliveryWindows": [
            {
              "startDate": "2022-12-11T08:00:00Z",
              "endDate": "2022-12-14T07:59:59Z"
            }
          ]
        },
        "isFulfillable": true,
        "isCODCapable": false,
        "estimatedShippingWeight": {
          "unit": "POUNDS",
          "value": "0.441"
        },
        "estimatedFees": [
          {
            "name": "FBAPerOrderFulfillmentFee",
            "amount": {
              "currencyCode": "YEN",
              "value": "0.0"
            }
          },
          {
            "name": "FBATransportationFee",
            "amount": {
              "currencyCode": "YEN",
              "value": "0.0"
            }
          },
          {
            "name": "FBAPerUnitFulfillmentFee",
            "amount": {
              "currencyCode": "YEN",
              "value": "9.82"
            }
          }
        ],
        "fulfillmentPreviewShipments": [
          {
            "earliestShipDate": "2022-12-11T08:00:00Z",
            "latestShipDate": "2022-12-12T07:59:59Z",
            "earliestArrivalDate": "2022-12-13T08:00:00Z",
            "latestArrivalDate": "2022-12-14T07:59:59Z",
            "fulfillmentPreviewItems": [
              {
                "sellerSku": "SellerSKU12",
                "quantity": 2,
                "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
                "estimatedShippingWeight": {
                  "unit": "POUNDS",
                  "value": "0.441"
                },
                "shippingWeightCalculationMethod": "Dimensional"
              }
            ]
          }
        ],
        "unfulfillablePreviewItems": [],
        "marketplaceId": "A1VC38T7YXB528"
      }
    ]
  }
}
NameDescription
FulfillmentPreviews

An array of fulfillment preview information.

Type: FulfillmentPreviewList

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the operation.

Type: ErrorList

Step 2. Create a fulfillment order

Call the createFulfillmentOrder operation with the Delivery Window obtained from the getFulfillmentPreview response and with ShippingSpeedCategory = ScheduledDelivery. If any other window is used with the createFulfillmentOrder operation, the service will return an error and getFulfillmentPreview operation will need to be rerun.

Body ParameterDescriptionRequired
marketplaceId

The marketplace the fulfillment order is placed against.

Type: string

No
sellerFulfillmentOrderId

A fulfillment order identifier that the seller creates to track their fulfillment order. The sellerFulfillmentOrderId must be unique for each fulfillment order that a seller creates. If the seller's system already creates unique order identifiers, then these might be good values for them to use.

maxLength : 40

Type: string

Yes
displayableOrderId

A fulfillment order identifier that the seller creates. This value displays as the order identifier in recipient-facing materials such as the outbound shipment packing slip. The value of DisplayableOrderId should match the order identifier that the seller provides to the recipient. The seller can use the SellerFulfillmentOrderId for this value or they can specify an alternate value if they want the recipient to reference an alternate order identifier.

The value must be an alpha-numeric or ISO 8859-1 compliant string from one to 40 characters in length. Cannot contain two spaces in a row. Leading and trailing white space is removed.

maxLength : 40

Type: string

Yes
displayableOrderDate

The date and time of the fulfillment order. Displays as the order date in recipient-facing materials such as the outbound shipment packing slip.

Type: Timestamp

Yes
displayableOrderComment

Order-specific text that appears in recipient-facing materials such as the outbound shipment packing slip.

maxLength : 250

Type: string

Yes
shippingSpeedCategory

The shipping method for the fulfillment order.

Type:

ShippingSpeedCategory
Yes
deliveryWindow

The time range within which a Scheduled Delivery fulfillment order should be delivered.

Type: DeliveryWindow

No
destinationAddress

The destination address for the fulfillment order.

Type: Address

Yes
fulfillmentAction

Specifies whether the fulfillment order should ship now or have an order hold put on it.

Type: FulfillmentAction

No
fulfillmentPolicy

The FulfillmentPolicy value specified when you submitted the createFulfillmentOrder operation.

Type: FulfillmentPolicy

No
codSettings

The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

Type: CODSettings

No
shipFromCountryCode

The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. It is Required if doing a cross border shipment.

Type: string

No
notificationEmails

A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

Type: NotificationEmailList

No
featureConstraints

A list of features and their fulfillment policies to apply to the order.

Type: < FeatureSettings > array

No
Items

A list of items to include in the fulfillment order preview, including quantity.

Type: CreateFulfillmentOrderItemList

Yes

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": "ScheduledDelivery",
  "deliveryWindow": {
    "startDate": "2022-12-11T08:00:00Z",
    "endDate": "2022-12-14T07:59:59Z"
  },
  "fulfillmentAction": "Ship",
  "destinationAddress": {
    "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-0",
      "quantity": 1
    }
  ]
}

Response

A successful response has a code of 200, and includes the objects below.

Response example

 {} 

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the createFulfillmentOrder operation.

Type: ErrorList

Step 3. Get the fulfillment order to validate order details

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

ParameterDescriptionRequired
sellerFulfillmentOrderId

The identifier assigned to the item by the seller when the fulfillment order was created

maxLength : 40

Type: string

Yes

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"

Response

A successful response has a code of 200 with a payload.

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"
      },
      "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": []
  }
}
Body ParameterDescriptionRequired
fulfillmentOrder

General information about a fulfillment order, including its status.

Type: FulfillmentOrder

Yes

fulfillmentOrderItems

An array of fulfillment order item information.

Type: FulfillmentOrderItemList

Yes
fulfillmentShipments

An array of fulfillment shipment information.

Type: FulfillmentShipmentList

No
returnItems

An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

Type: ReturnItemList

Yes
returnAuthorizations

An array of return authorization information.

Type: ReturnAuthorizationList

Yes

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the operation.

Type: ErrorList

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 will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

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).

Body ParameterDescriptionRequired
marketplaceId

The marketplace the fulfillment order is placed against.

Type: string

No
address

The destination address for the fulfillment order preview.

Type: Address

Yes
items

Identifying information and quantity information for the items in the fulfillment order preview.

Type: GetFulfillmentPreviewItemList

Yes
shippingSpeedCategories

A list of shipping methods used for creating fulfillment order previews.

Possible Values:

  • Standard - Standard shipping method.
  • Expedited - Expedited shipping method.
  • Priority - Priority shipping method.
  • ScheduledDelivery - Scheduled Delivery shipping method only for Japan.

Note: Shipping method service level agreements vary by marketplace. Sellers should see the Seller Central website in their marketplace for shipping method service level agreements and fulfillment fees.

No
includeCODFulfillmentPreview

Specifies whether to return fulfillment order previews that are for COD (Cash On Delivery).

Possible values:

  • true - Returns all fulfillment order previews (both for COD and not for COD).
  • false - Returns only fulfillment order previews that are not for COD.

Only applicable for orders in Japan.

Type: boolean

No
includeDeliveryWindows

Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The ScheduledDeliveryInfo response object can only be returned for fulfillment order previews with ShippingSpeedCategories = ScheduledDelivery. Only applicable for orders in Japan.

Type: boolean

No
featureConstraints

A list of features and their fulfillment policies to apply to the order.

Type: < FeatureSettings > array

No

Request example

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

{
  "marketplaceId": "ATVPDKIKX0DER",
  "address": {
    "name": "Mary Major",
    "addressLine1": "Stockton Street",
    "city": "Alexandria",
    "stateOrRegion": "VA",
    "countryCode": "US",
    "postalCode": "22308"
  },
  "items": [
    {
      "sellerSku": "LT205BTBLKAM",
      "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
      "quantity": 2
    }
  ],
  "shippingSpeedCategories": [
    "Standard"
  ]
}

Response

A successful response has a code of 200, and the response schema for the getFulfillmentPreview operation.

{
  "payload": {
    "fulfillmentPreviews": [
      {
        "shippingSpeedCategory": "Standard",
        "isFulfillable": true,
        "isCODCapable": false,
        "estimatedShippingWeight": {
          "unit": "POUNDS",
          "value": "0.441"
        },
        "estimatedFees": [
          {
            "name": "FBAPerOrderFulfillmentFee",
            "amount": {
              "currencyCode": "USD",
              "value": "0.0"
            }
          },
          {
            "name": "FBATransportationFee",
            "amount": {
              "currencyCode": "USD",
              "value": "0.0"
            }
          },
          {
            "name": "FBAPerUnitFulfillmentFee",
            "amount": {
              "currencyCode": "USD",
              "value": "9.82"
            }
          }
        ],
        "fulfillmentPreviewShipments": [
          {
            "earliestShipDate": "2022-12-11T08:00:00Z",
            "latestShipDate": "2022-12-12T07:59:59Z",
            "earliestArrivalDate": "2022-12-13T08:00:00Z",
            "latestArrivalDate": "2022-12-14T07:59:59Z",
            "fulfillmentPreviewItems": [
              {
                "sellerSku": "LT205BTBLKAM",
                "quantity": 2,
                "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
                "estimatedShippingWeight": {
                  "unit": "POUNDS",
                  "value": "0.379"
                },
                "shippingWeightCalculationMethod": "Dimensional"
              }
            ]
          }
        ],
        "unfulfillablePreviewItems": [],
        "marketplaceId": "ATVPDKIKX0DER"
      }
    ]
  }
}
NameDescription
fulfillmentPreviews

An array of fulfillment preview information.

Type: FulfillmentPreviewList

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

NameDescription
errors

One or more unexpected errors occurred during the getFulfillmentPreview operation.

Type: ErrorList

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.

Body ParameterDescriptionRequired
marketplaceId

The marketplace the fulfillment order is placed against.

Type: string

No
sellerFulfillmentOrderIdA fulfillment order identifier that the seller creates to track their fulfillment order. The

sellerFulfillmentOrderId must be unique for each fulfillment order that a seller creates. If the seller's system already creates unique order identifiers, then these might be good values for them to use.

maxLength : 40

Type: string

Yes
displayableOrderIdA fulfillment order identifier that the seller creates. This value displays as the order identifier in recipient-facing materials such as the outbound shipment packing slip. The value of DisplayableOrderId should match the order identifier that the seller provides to the recipient. The seller can use the SellerFulfillmentOrderId for this value or they can specify an alternate value if they want the recipient to reference an alternate order identifier. The value must be an alpha-numeric or ISO 8859-1 compliant string from one to 40 characters in length. Cannot contain two spaces in a row. Leading and trailing white space is removed.

maxLength : 40

Type: string

displayableOrderDate

The date and time of the fulfillment order. Displays as the order date in recipient-facing materials such as the outbound shipment packing slip.

Type: Timestamp

Yes
displayableOrderComment

Order-specific text that appears in recipient-facing materials such as the outbound shipment packing slip.

maxLength : 250

Type: string

Yes
shippingSpeedCategory

The shipping method for the fulfillment order.

Type: ShippingSpeedCategory

Yes
deliveryWindow

The time range within which a Scheduled Delivery fulfillment order should be delivered.

Type: DeliveryWindow

No
destinationAddress

The destination address for the fulfillment order.

Type: Address

Yes
fulfillmentAction

Specifies whether the fulfillment order should ship now or have an order hold put on it.

Type: FulfillmentAction

No
fulfillmentPolicy

The FulfillmentPolicy value specified when you submitted the createFulfillmentOrder operation.

Type: FulfillmentPolicy

No
codSettings

The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

Type: CODSettings

No
shipFromCountryCode

The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. It is Required if doing a cross border shipment.

Type: string

No
notificationEmails

A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

Type: NotificationEmailList

No
featureConstraints

A list of features and their fulfillment policies to apply to the order.

Type: < FeatureSettings >

No
Items

A list of items to include in the fulfillment order preview, including quantity.

Type: CreateFulfillmentOrderItemList

Yes

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",
  "destinationAddress": {
    "name": "Mary Major",
    "addressLine1": "123 Any Street",
    "city": "Any Town",
    "stateOrRegion": "VA",
    "countryCode": "US",
    "postalCode": "22308"
  },
  "items": [
    {
      "sellerSku": "LT110WHTAM",
      "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
      "quantity": 1
    },
    {
      "sellerSku": "LT205BLKAM",
      "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
      "quantity": 1
    }
  ]
}

Response

A successful response has a code of 200, and includes the objects below.

Response example

{}

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescription
errors

One or more unexpected errors occurred during the createFulfillmentOrder operation.

Type: ErrorList

Step 3. Validate the order details

Call the getFulfillmentOrder operation to validate fulfillmentAction = Ship and fulfillmentOrderStatus = Received.

ParameterDescriptionRequired
sellerFulfillmentOrderId

The identifier assigned to the item by the seller when the fulfillment order was created.

maxLength : 40

Type: string

Yes

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045 "

Response

A successful response has a code of 200 with a payload.

Response example

{
  "payload": {
    "fulfillmentOrder": {
      "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
      "marketplaceId": "ATVPDKIKX0DER",
      "displayableOrderId": "CONSUMER-2022921-145045",
      "displayableOrderDate": "2022-09-21T14:48:15Z",
      "displayableOrderComment": "TestOrder",
      "shippingSpeedCategory": "Standard",
      "destinationAddress": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Any Town",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "fulfillmentAction": "Ship",
      "fulfillmentPolicy": "FillAllAvailable",
      "receivedDate": "2022-09-21T14:50:45Z",
      "fulfillmentOrderStatus": "Received",
      "statusUpdatedDate": "2022-09-22T03:44:35Z",
      "notificationEmails": [
        "[email protected]"
      ],
      "featureConstraints": [
        {
          "featureName": "BLANK_BOX",
          "featureFulfillmentPolicy": "NotRequired"
        }
      ]
    },
    "fulfillmentOrderItems": [
      {
        "sellerSku": "LT110WHTAM",
        "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
        "quantity": "1",
        "fulfillmentNetworkSku": "X002ZKH36D",
        "orderItemDisposition": "Sellable",
        "cancelledQuantity": "0",
        "unfulfillableQuantity": "1",
        "estimatedShipDate": "2022-09-22T06:59:59Z",
        "estimatedArrivalDate": "2022-09-26T06:59:59Z",
        "perUnitDeclaredValue": {
          "currencyCode": "USD",
          "value": "0.00"
        }
      },
      {
        "sellerSku": "LT205BLKAM",
        "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
        "quantity": "1",
        "giftMessage": "",
        "fulfillmentNetworkSku": "X002ZKYQ4Z",
        "orderItemDisposition": "Sellable",
        "cancelledQuantity": "0",
        "unfulfillableQuantity": "0",
        "estimatedShipDate": "",
        "estimatedArrivalDate": "",
        "perUnitDeclaredValue": {
          "currencyCode": "USD",
          "value": "1995.00"
        }
      }
    ],
    "fulfillmentShipments": [],
    "returnItems": [],
    "returnAuthorizations": []
  }
}
Body ParameterDescriptionRequired
fulfillmentOrder

General information about a fulfillment order, including its status.

Type: FulfillmentOrder

Yes
fulfillmentOrderItems

An array of fulfillment order item information.

Type: FulfillmentOrderItemList

Yes
fulfillmentShipments

An array of fulfillment shipment information.

Type: FulfillmentShipmentList

No
returnItems

An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

Type: ReturnItemList

Yes
returnAuthorizations

An array of return authorization information.

Type: ReturnAuthorizationList

Yes

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescriptionRequired
errors

One or more unexpected errors occurred during the getFulfillmentOrder operation.

Type: ErrorList

Yes

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. Subscribe and listen to FULFILLMENT_ORDER_STATUS notifications to be aware of these status changes.

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

Once the order is Shipped, the order status notification for Complete is triggered. Now call the getFulfillmentOrder operation to see the latest order details. Call the getFulfillmentOrder operation by passing the following parameters:

ParameterDescriptionRequired
sellerFulfillmentOrderId

The identifier assigned to the item by the seller when the fulfillment order was created.

maxLength : 40

Type: string

Yes

Request example

GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"

Response

A successful response has a code of 200 with a payload.

Response example

{
  "payload": {
    "fulfillmentOrder": {
      "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
      "marketplaceId": "ATVPDKIKX0DER",
      "displayableOrderId": "CONSUMER-2022921-145045",
      "displayableOrderDate": "2022-09-21T14:48:15Z",
      "displayableOrderComment": "Thank you for your order",
      "shippingSpeedCategory": "Standard",
      "destinationAddress": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Any Town",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "fulfillmentAction": "Ship",
      "fulfillmentPolicy": "FillAllAvailable",
      "receivedDate": "2022-09-21T14:50:45Z",
      "fulfillmentOrderStatus": "CompletePartialled",
      "statusUpdatedDate": "2022-09-22T03:44:35Z",
      "notificationEmails": [
        "[email protected]"
      ],
      "featureConstraints": [
        {
          "featureName": "BLANK_BOX",
          "featureFulfillmentPolicy": "NotRequired"
        }
      ]
    },
    "fulfillmentOrderItems": [
      {
        "sellerSku": "LT110WHTAM",
        "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
        "quantity": "1",
        "fulfillmentNetworkSku": "X002ZKH36D",
        "orderItemDisposition": "Sellable",
        "cancelledQuantity": "0",
        "unfulfillableQuantity": "0",
        "estimatedShipDate": "2022-09-22T06:59:59Z",
        "estimatedArrivalDate": "2022-09-26T06:59:59Z",
        "perUnitDeclaredValue": {
          "currencyCode": "USD",
          "value": "0.00"
        }
      },
      {
        "sellerSku": "LT205BLKAM",
        "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
        "quantity": "1",
        "giftMessage": "",
        "fulfillmentNetworkSku": "X002ZKYQ4Z",
        "orderItemDisposition": "Sellable",
        "cancelledQuantity": "0",
        "unfulfillableQuantity": "1",
        "estimatedShipDate": "",
        "estimatedArrivalDate": "",
        "perUnitDeclaredValue": {
          "currencyCode": "USD",
          "value": "1995.00"
        }
      }
    ],
    "fulfillmentShipments": [
      {
        "amazonShipmentId": "T7mfkbDX5",
        "fulfillmentCenterId": "TUL2",
        "fulfillmentShipmentStatus": "SHIPPED",
        "shippingDate": "2022-09-22T03:39:19Z",
        "estimatedArrivalDate": "2022-09-26T06:59:59Z",
        "fulfillmentShipmentItem": [
          {
            "sellerSku": "LT205BLKAM",
            "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
            "quantity": "1",
            "packageNumber": "1681854637"
          }
        ],
        "fulfillmentShipmentPackage": [
          {
            "packageNumber": "1681854637",
            "carrierCode": "Amazon Logistics",
            "trackingNumber": "TBA303037991486",
            "estimatedArrivalDate": "2022-09-26T03:00:00Z"
          }
        ]
      }
    ],
    "returnItems": [],
    "returnAuthorizations": []
  }
}
Body ParameterDescriptionRequired
fulfillmentOrder

General information about a fulfillment order, including its status.

Type: FulfillmentOrder

Yes
fulfillmentOrderItems

An array of fulfillment order item information.

Type: FulfillmentOrderItemList

Yes
fulfillmentShipments

An array of fulfillment shipment information.

Type: FulfillmentShipmentList

No
returnItems

An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

Type: ReturnItemList

Yes
returnAuthorizations

An array of return authorization information.

Type: ReturnAuthorizationList

Yes

An unsuccessful response has a code of non-2xx, and includes the objects below.

NameDescriptionRequired
errors

One or more unexpected errors occurred during the getFulfillmentOrder operation.

Type: ErrorList

Yes

Step 6. Validate the order status and line item quantities

Validate fulfillmentShipmentStatus = Shipped and fulfillmentOrderStatus = CompletePartialled. If there are items that have unfulfillableQuantity !=0, that implies that 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.

ParameterDescriptionRequired
packageNumber

The unencrypted package identifier returned by the getFulfillmentOrder operation.

Type: integer (int32)

Yes

Request example

GET โ€œhttps://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/tracking?packageNumber=1681854637โ€

Response

A successful response has a code of 200.

Response example

{
  "payload": {
    "packageNumber": 1681854637,
    "trackingNumber": "TBA303037991486",
    "carrierCode": "Amazon",
    "carrierURL": "https://www.swiship.com/track?id=TBA303037991486",
    "shipDate": "2022-09-22T03:57:50Z",
    "estimatedArrivalDate": "2022-09-26T03:00:00Z",
    "shipToAddress": {
      "city": "Alexandria",
      "state": "VA",
      "country": "US"
    },
    "currentStatus": "DELIVERED",
    "additionalLocationInfo": "FRONT_DOOR/PORCH",
    "trackingEvents": [
      {
        "eventDate": "2022-09-25T16:55:51Z",
        "eventAddress": {
          "city": "Alexandria",
          "country": "US"
        },
        "eventCode": "EVENT_301",
        "eventDescription": "Package delivered near the front door or porch."
      },
      {
        "eventDate": "2022-09-25T14:29:43Z",
        "eventAddress": {
          "city": "Waldorf",
          "country": "US"
        },
        "eventCode": "EVENT_302",
        "eventDescription": "Package is out for delivery."
      },
      {
        "eventDate": "2022-09-25T01:00:54Z",
        "eventAddress": {
          "city": "Sparrows Point",
          "state": "Maryland",
          "country": "US"
        },
        "eventCode": "EVENT_201",
        "eventDescription": "Package arrived at an Amazon facility."
      },
      {
        "eventDate": "2022-09-24T20:50:45Z",
        "eventAddress": {
          "city": "Trenton",
          "state": "NJ",
          "country": "US"
        },
        "eventCode": "EVENT_202",
        "eventDescription": "Package left an Amazon facility."
      },
      {
        "eventDate": "2022-09-24T08:35:48Z",
        "eventAddress": {
          "city": "Trenton",
          "state": "NJ",
          "country": "US"
        },
        "eventCode": "EVENT_201",
        "eventDescription": "Package arrived at an Amazon facility."
      },
      {
        "eventDate": "2022-09-23T06:54:31Z",
        "eventAddress": {
          "city": "Liberty",
          "state": "Missouri",
          "country": "US"
        },
        "eventCode": "EVENT_202",
        "eventDescription": "Package left an Amazon facility."
      },
      {
        "eventDate": "2022-09-22T23:15:03Z",
        "eventAddress": {
          "city": "Liberty",
          "state": "Missouri",
          "country": "US"
        },
        "eventCode": "EVENT_201",
        "eventDescription": "Package arrived at an Amazon facility."
      },
      {
        "eventDate": "2022-09-22T03:57:50Z",
        "eventCode": "EVENT_101",
        "eventDescription": "Carrier picked up the package."
      }
    ]
  }
}
NameDescriptionRequired
packageNumber

The package identifier.

Type: integer (int32)

Yes
trackingNumber

The tracking number for the package.

Type: string

No
customerTrackingLink

Link on swiship.com that allows customers to track the package.

Type: string

No
carrierCode

The name of the carrier.

Type: string

No
carrierPhoneNumber

The phone number of the carrier.

Type: string

No
carrierURL

The URL of the carrierโ€™s website.

Type: string

No
shipDate

The shipping date for the package.

Type: Timestamp

No
estimatedArrivalDate

The estimated arrival date.

Type: Timestamp

No
shipToAddress

The destination city for the package.

Type: TrackingAddress

No
currentStatus

The current delivery status of the package.

Type: CurrentStatus

No
currentStatusDescription

Description corresponding to the CurrentStatus value.

Type: string

No
signedForBy

The name of the person who signed for the package.

Type: string

No
additionalLocationInfo

Additional location information.

Type: AdditionalLocationInfo

No
trackingEvents

An array of tracking event information.

Type: TrackingEventList

No

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

NameDescription
errors

One or more unexpected errors occurred during the getPackageTrackingDetails operation.

Type: ErrorList

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 will not proceed to further fulfillment actions until the status is updated to SHIP.

Prerequisites

To complete this tutorial you will need:

  1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
  2. The Amazon Fulfillment role assigned to your developer profile.
  3. The Amazon Fulfillment role selected in the App registration page for your application.

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).

Body ParameterDescriptionRequired
marketplaceId

The marketplace the fulfillment order is placed against.

Type: string

No
address

The destination address for the fulfillment order preview.

Type: Address

Yes
items

Identifying information and quantity information for the items in the fulfillment order preview.

Type: GetFulfillmentPreviewItemList

Yes
shippingSpeedCategories

A list of shipping methods used for creating fulfillment order previews.

Possible Values:

  • Standard - Standard shipping method
  • Expedited - Expedited shipping method
  • Priority - Priority shipping method.
  • ScheduledDelivery - Scheduled Delivery shipping method only for Japan.

Note: Shipping method service level agreements vary by marketplace. Sellers should see the Seller Central website in their marketplace for shipping method service level agreements and fulfillment fees.

No
includeCODFulfillmentPreview

Specifies whether to return fulfillment order previews that are for COD (Cash On Delivery).

Possible values:

  • true - Returns all fulfillment order previews (both for COD and not for COD).
  • false - Returns only fulfillment order previews that are not for COD. Only applicable for orders in Japan.

  • Type: boolean

    No
    includeDeliveryWindows

    Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The ScheduledDeliveryInfo response object can only be returned for fulfillment order previews with ShippingSpeedCategories = ScheduledDelivery. Only applicable for orders in Japan.

    Type: boolean

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type: < FeatureSettings > array

    No

    Request example

    POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview"
    
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "address": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Anytown",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "items": [
        {
          "sellerSku": "LT205BTBLKAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
          "quantity": 2
        }
      ],
      "shippingSpeedCategories": [
        "Standard"
      ]
    }
    
    NameDescription
    fulfillmentPreviews

    An array of fulfillment preview information.

    Type: FulfillmentPreviewList

    An unsuccessful response has a code of non-2xx, and includes the objects below. A 404 response will provide the ineligibility errors, if any.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentPreview operation.

    Type: ErrorList

    Yes

    Step 2. Create a fulfillment order on hold.

    Call the createFulfillmentOrder operation with one or more line items with fulfillmentAction=Hold in the request. Doing so keeps the order in Hold status and further fulfillment actions will not execute on that order.

    Body ParameterDescriptionRequired
    marketplaceId

    The marketplace the fulfillment order is placed against.

    Type: string

    No
    sellerFulfillmentOrderId

    A fulfillment order identifier that the seller creates to track their fulfillment order. The sellerFulfillmentOrderId must be unique for each fulfillment order that a seller creates. If the seller's system already creates unique order identifiers, then these might be good values for them to use.

    maxLength : 40

    Type: string

    Yes
    displayableOrderId

    A fulfillment order identifier that the seller creates. This value displays as the order identifier in recipient-facing materials such as the outbound shipment packing slip. The value of DisplayableOrderId should match the order identifier that the seller provides to the recipient. The seller can use the SellerFulfillmentOrderId for this value or they can specify an alternate value if they want the recipient to reference an alternate order identifier. The value must be an alpha-numeric or ISO 8859-1 compliant string from one to 40 characters in length. Cannot contain two spaces in a row. Leading and trailing white space is removed.

    maxLength : 40

    Type: string

    Yes
    displayableOrderDate

    The date and time of the fulfillment order. Displays as the order date in recipient-facing materials such as the outbound shipment packing slip.

    Type: Timestamp

    Yes
    displayableOrderComment

    Order-specific text that appears in recipient-facing materials such as the outbound shipment packing slip.

    maxLength : 250

    Type: string

    Yes
    shippingSpeedCategory

    The shipping method for the fulfillment order.

    Type: ShippingSpeedCategory

    Yes
    deliveryWindow

    The time range within which a Scheduled Delivery fulfillment order should be delivered.

    Type: DeliveryWindow

    No
    destinationAddress

    The destination address for the fulfillment order.

    Type: Address

    Yes
    fulfillmentAction

    Specifies whether the fulfillment order should ship now or have an order hold put on it.

    Type: FulfillmentAction

    No
    fulfillmentPolicy

    The `FulfillmentPolicy` value specified when you submitted the createFulfillmentOrder operation.

    Type: FulfillmentPolicy

    No
    codSettings

    The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

    Type: CODSettings

    No
    shipFromCountryCode

    The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. It is Required if doing a cross border shipment.

    Type: string

    No
    notificationEmails

    A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

    Type: NotificationEmailList

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type: < FeatureSettings > array

    No
    Items

    A list of items to include in the fulfillment order preview, including quantity.

    Type: CreateFulfillmentOrderItemList

    Yes

    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": "Hold",
      "destinationAddress": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Alexandria",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "items": [
        {
          "sellerSku": "LT110WHTAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
          "quantity": 1
        },
        {
          "sellerSku": "LT205BLKAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
          "quantity": 1
        }
      ]
    }
    

    Response

    A successful response has a code of 200, and includes the objects below.

    Response example

    {}
    

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescription
    errors

    One or more unexpected errors occurred during the createFulfillmentOrder operation.

    Type: ErrorList

    Step 3. Update the order fulfillment action to ship

    Call the updateFulfillmentOrder operation to update the order with fulfillmentAction = Ship in the request body to move the order from Hold to Ship.

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created.

    Type: string

    Yes

    Request example

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

    Response

    A successful response has a code of 200.

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescription
    errors

    One or more unexpected errors occurred during the UpdateFulfillmentOrderResponse operation.

    Type: ErrorList

    Step 4. Get the fulfillment order to validate the changes

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

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created

    maxLength : 40

    Type: string

    Yes

    Request example

    GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"
    

    Response

    A successful response has a code of 200 with a payload.

    Response example

    {
      "payload": {
        "fulfillmentOrder": {
          "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
          "marketplaceId": "ATVPDKIKX0DER",
          "displayableOrderId": "CONSUMER-2022921-145045",
          "displayableOrderDate": "2022-09-21T14:48:15Z",
          "displayableOrderComment": "TestOrder",
          "shippingSpeedCategory": "Standard",
          "destinationAddress": {
            "name": "Mary Major",
            "addressLine1": "123 Any Street",
            "city": "Alexandria",
            "stateOrRegion": "VA",
            "countryCode": "US",
            "postalCode": "22308"
          },
          "fulfillmentAction": "Ship",
          "fulfillmentPolicy": "FillAllAvailable",
          "receivedDate": "2022-09-21T14:50:45Z",
          "fulfillmentOrderStatus": "Received",
          "statusUpdatedDate": "2022-09-22T03:44:35Z",
          "notificationEmails": [
            "[email protected]"
          ],
          "featureConstraints": [
            {
              "featureName": "BLANK_BOX",
              "featureFulfillmentPolicy": "NotRequired"
            }
          ]
        },
        "fulfillmentOrderItems": [
          {
            "sellerSku": "LT110WHTAM",
            "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
            "quantity": "1"
          },
          {
            "sellerSku": "LT205BLKAM",
            "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
            "quantity": "1"
          }
        ],
        "fulfillmentShipments": [],
        "returnItems": [],
        "returnAuthorizations": []
      }
    }
    
    Body ParameterDescriptionRequired
    fulfillmentOrder

    General information about a fulfillment order, including its status.

    Type: FulfillmentOrder

    Yes
    fulfillmentOrderItems

    An array of fulfillment order item information.

    Type: FulfillmentOrderItemList

    Yes
    fulfillmentShipments

    An array of fulfillment shipment information.

    Type: FulfillmentShipmentList

    No
    returnItems

    An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

    Type: ReturnItemList

    Yes
    returnAuthorizations

    An array of return authorization information.

    Type: ReturnAuthorizationList

    Yes

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentOrder operation.

    Type: ErrorList

    Yes

    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.

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

    Prerequisites

    1. The seller needs to share the Regex of the generated serial numbers with Amazon.
    2. The seller needs to paste the generated unique serial number on every item when inbounding the inventory to Amazon.
    3. 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.
    4. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
    5. The Amazon Fulfillment role assigned to your developer profile.
    6. 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 will not need any exclusive attributes in the request for this type of order.

    Body ParameterDescriptionRequired
    marketplaceId

    The marketplace the fulfillment order is placed against.

    Type: string

    No
    sellerFulfillmentOrderId

    A fulfillment order identifier that the seller creates to track their fulfillment order. The sellerFulfillmentOrderId must be unique for each fulfillment order that a seller creates. If the seller's system already creates unique order identifiers, then these might be good values for them to use.

    maxLength : 40

    Type: string

    Yes
    displayableOrderId

    A fulfillment order identifier that the seller creates. This value displays as the order identifier in recipient-facing materials such as the outbound shipment packing slip. The value of DisplayableOrderId should match the order identifier that the seller provides to the recipient. The seller can use the SellerFulfillmentOrderId for this value or they can specify an alternate value if they want the recipient to reference an alternate order identifier.

    The value must be an alpha-numeric or ISO 8859-1 compliant string from one to 40 characters in length. Cannot contain two spaces in a row. Leading and trailing white space is removed.

    Yes
    displayableOrderDate

    The date and time of the fulfillment order. Displays as the order date in recipient-facing materials such as the outbound shipment packing slip.

    Type: Timestamp

    Yes
    displayableOrderComment

    Order-specific text that appears in recipient-facing materials such as the outbound shipment packing slip.

    maxLength : 250

    Type: string

    Yes
    shippingSpeedCategory

    The shipping method for the fulfillment order.

    Type: ShippingSpeedCategory

    Yes
    deliveryWindow

    The time range within which a Scheduled Delivery fulfillment order should be delivered.

    Type: DeliveryWindow

    No
    destinationAddress

    The destination address for the fulfillment order.

    Type: Address

    Yes
    fulfillmentAction

    Specifies whether the fulfillment order should ship now or have an order hold put on it.

    Type: FulfillmentAction

    No
    fulfillmentPolicy

    The FulfillmentPolicy value specified when you submitted the createFulfillmentOrder operation.

    Type: FulfillmentPolicy

    No
    codSettings

    The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

    Type: CODSettings

    No
    shipFromCountryCode

    The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. It is Required if doing a cross border shipment.

    Type: string

    No
    notificationEmails

    A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

    Type: NotificationEmailList

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type:< FeatureSettings > array

    No
    Items

    A list of items to include in the fulfillment order preview, including quantity.

    Type: CreateFulfillmentOrderItemList

    Yes

    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",
      "destinationAddress": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Alexandria",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "items": [
        {
          "sellerSku": "LT110WHTAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
          "quantity": 1
        }
      ]
    }
    

    Response

    A successful response has a code of 200, and includes the objects below.

    Response example

    {}
    

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescription
    errors

    One or more unexpected errors occurred during the createFulfillmentOrder operation.

    Type: ErrorList

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

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

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created

    maxLength : 40

    Type: string

    Yes

    Request example

    GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"
    

    Response

    A successful response has a code of 200 with a payload.

    Response example

    {
      "payload": {
        "fulfillmentOrder": {
          "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
          "marketplaceId": "ATVPDKIKX0DER",
          "displayableOrderId": "CONSUMER-2022921-145045",
          "displayableOrderDate": "2022-01-09T19:46:45.809Z",
          "displayableOrderComment": "TestOrder",
          "shippingSpeedCategory": "Standard",
          "destinationAddress": {
            "name": "Mary Major",
            "addressLine1": "123 Any Street",
            "city": "Alexandria",
            "stateOrRegion": "VA",
            "countryCode": "US",
            "postalCode": "22308"
          },
          "fulfillmentAction": "Ship",
          "fulfillmentPolicy": "FillAllAvailable",
          "receivedDate": "2022-09-21T14:50:45Z",
          "fulfillmentOrderStatus": "Received",
          "statusUpdatedDate": "2022-09-22T03:44:35Z",
          "notificationEmails": [
            "[email protected]"
          ],
          "fulfillmentOrderItems": [
            {
              "sellerSku": "LT110WHTAM",
              "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
              "quantity": "1"
            }
          ],
          "fulfillmentShipments": [],
          "returnItems": [],
          "returnAuthorizations": []
        }
      }
    }
    
    Body ParameterDescriptionRequired
    fulfillmentOrder

    General information about a fulfillment order, including its status.

    Type: FulfillmentOrder

    Yes
    fulfillmentOrderItems

    An array of fulfillment order item information.

    Type: FulfillmentOrderItemList

    Yes
    fulfillmentShipments

    An array of fulfillment shipment information.

    Type: FulfillmentShipmentList

    No
    returnItems

    An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

    Type: ReturnItemList

    Yes
    returnAuthorizations

    An array of return authorization information.

    Type: ReturnAuthorizationList

    Yes

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentOrder operation.

    Type: ErrorList

    Yes

    Step 3. Get the fulfillment order to track status changes

    The order will go 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 see the latest order details and check if the serial number of the item was shipped.

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created.

    maxLength : 40

    Type: string

    Yes

    Request example

    GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045 "
    

    Response

    A successful response has a code of 200 with a payload.

    Response example

    {
      "payload": {
        "fulfillmentOrder": {
          "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
          "marketplaceId": "ATVPDKIKX0DER",
          "displayableOrderId": "CONSUMER-2022921-145045",
          "displayableOrderDate": "2022-09-21T14:48:15Z",
          "displayableOrderComment": "TestOrder1",
          "shippingSpeedCategory": "Standard",
          "destinationAddress": {
            "name": "Mary Major",
            "addressLine1": "123 Any Street",
            "city": "Any Town",
            "stateOrRegion": "VA",
            "countryCode": "US",
            "postalCode": "22308"
          },
          "fulfillmentAction": "Ship",
          "fulfillmentPolicy": "FillAllAvailable",
          "receivedDate": "2022-09-21T14:50:45Z",
          "fulfillmentOrderStatus": "Complete",
          "statusUpdatedDate": "2022-09-22T03:44:35Z",
          "notificationEmails": [
            "[email protected]"
          ],
          "featureConstraints": [
            {
              "featureName": "BLANK_BOX",
              "featureFulfillmentPolicy": "NotRequired"
            }
          ]
        },
        "fulfillmentOrderItems": [
          {
            "sellerSku": "LT110WHTAM",
            "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
            "quantity": "1",
            "fulfillmentNetworkSku": "X002ZKH36D",
            "orderItemDisposition": "Sellable",
            "cancelledQuantity": "0",
            "unfulfillableQuantity": "0",
            "estimatedShipDate": "2022-09-22T06:59:59Z",
            "estimatedArrivalDate": "2022-09-26T06:59:59Z",
            "perUnitDeclaredValue": {
              "currencyCode": "USD",
              "value": "100.00"
            }
          }
        ],
        "fulfillmentShipments": [
          {
            "amazonShipmentId": "T7mfkbDX5",
            "fulfillmentCenterId": "TUL2",
            "fulfillmentShipmentStatus": "SHIPPED",
            "shippingDate": "2022-09-22T03:39:19Z",
            "estimatedArrivalDate": "2022-09-26T06:59:59Z",
            "fulfillmentShipmentItem": [
              {
                "sellerSku": "LT110WHTAM",
                "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
                "quantity": "1",
                "packageNumber": "1681854637",
                "serialNumber": "355313088062664"
              }
            ],
            "fulfillmentShipmentPackage": [
              {
                "packageNumber": "1681854637",
                "carrierCode": "Amazon Logistics",
                "trackingNumber": "TBA303037991486",
                "estimatedArrivalDate": "2022-09-26T03:00:00Z"
              }
            ]
          }
        ],
        "returnItems": [],
        "returnAuthorizations": []
      }
    }
    
    Body ParameterDescriptionRequired
    fulfillmentOrder

    General information about a fulfillment order, including its status.

    Type: FulfillmentOrder

    Yes
    fulfillmentOrderItems

    An array of fulfillment order item information.

    Type: FulfillmentOrderItemList

    Yes
    fulfillmentShipments

    An array of fulfillment shipment information.

    Type: FulfillmentShipmentList

    No
    returnItems

    An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

    Type: ReturnItemList

    Yes
    returnAuthorizations

    An array of return authorization information.

    Type: ReturnAuthorizationList

    Yes

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentOrder operation.

    Type: ErrorList

    Yes

    Step 4. Validate the order status and line item quantities

    Validate fulfillmentShipmentStatus=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 will need:

    1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
    2. The Amazon Fulfillment role assigned to your developer profile.
    3. The Amazon Fulfillment role selected in the App registration page for your application.

    Step 1. Create a Fulfillment order for cross border shipment

    Create an order with US destination address and shipFromCountryCode=CA. In this case, we can skip specifying the marketplaceId in the request and the item will be picked from the CA marketplace. Call the createFulfillmentOrder operation by passing the following required Body parameters:

    Body ParameterDescriptionRequired
    marketplaceIdThe marketplace the fulfillment order is placed against.No
    sellerFulfillmentOrderId

    A fulfillment order identifier that the seller creates to track their fulfillment order. The sellerFulfillmentOrderId must be unique for each fulfillment order that a seller creates. If the seller's system already creates unique order identifiers, then these might be good values for them to use.

    maxLength : 40

    Type: string

    Yes
    displayableOrderId

    A fulfillment order identifier that the seller creates. This value displays as the order identifier in recipient-facing materials such as the outbound shipment packing slip. The value of DisplayableOrderId should match the order identifier that the seller provides to the recipient. The seller can use the SellerFulfillmentOrderId for this value or they can specify an alternate value if they want the recipient to reference an alternate order identifier. The value must be an alpha-numeric or ISO 8859-1 compliant string from one to 40 characters in length. Cannot contain two spaces in a row. Leading and trailing white space is removed.

    maxLength : 40

    Type: string

    Yes
    displayableOrderDate

    The date and time of the fulfillment order. Displays as the order date in recipient-facing materials such as the outbound shipment packing slip.

    Type: Timestamp

    Yes
    displayableOrderComment

    Order-specific text that appears in recipient-facing materials such as the outbound shipment packing slip.

    maxLength : 250

    Type: string

    Yes
    shippingSpeedCategory

    The shipping method for the fulfillment order.

    Type: ShippingSpeedCategory

    Yes
    deliveryWindow

    The time range within which a Scheduled Delivery fulfillment order should be delivered.

    Type: DeliveryWindow

    No
    destinationAddress

    The destination address for the fulfillment order.

    Type: Address

    Yes
    fulfillmentAction

    Specifies whether the fulfillment order should ship now or have an order hold put on it.

    Type: FulfillmentAction

    No
    fulfillmentPolicy

    The FulfillmentPolicy value specified when you submitted the createFulfillmentOrder operation.

    Type: FulfillmentPolicy

    No
    codSettings

    The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

    Type: CODSettings

    No
    shipFromCountryCode

    The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. It is Required if doing a cross border shipment.

    Type: string

    No
    notificationEmails

    A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

    Type: NotificationEmailList

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type: < FeatureSettings > array

    No
    Items

    A list of items to include in the fulfillment order preview, including quantity.

    Type: CreateFulfillmentOrderItemList

    Yes

    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": "123 Any Street",
        "city": "Any Town",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "items": [
        {
          "sellerSku": "LT205BLKAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
          "quantity": 1
        }
      ]
    }
    

    Response

    A successful response has a code of 200, and includes the objects below.

    Response example

    {}
    

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescription
    errors

    One or more unexpected errors occurred during the createFulfillmentOrder operation.

    Type: ErrorList

    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.

    Once 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 will need:

    1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
    2. The Amazon Fulfillment role assigned to your developer profile.
    3. The Amazon Fulfillment role selected in the App registration page for your application.

    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.

    Call the getFulfillmentPreview operation by passing the following body parameters:

    Body ParameterDescriptionRequired
    marketplaceId

    The marketplace the fulfillment order is placed against.

    Type: string

    No
    address

    The destination address for the fulfillment order preview.

    Type: Address

    Yes
    items

    Identifying information and quantity information for the items in the fulfillment order preview.

    Type: GetFulfillmentPreviewItemList

    Yes
    shippingSpeedCategories

    A list of shipping methods used for creating fulfillment order previews.

    Possible Values:

    • Standard - Standard shipping method.
    • Expedited - Expedited shipping method.
    • Priority - Priority shipping method.
    • ScheduledDelivery - Scheduled Delivery shipping method only for Japan.

    Note: Shipping method service level agreements vary by marketplace. Sellers should see the Seller Central website in their marketplace for shipping method service level agreements and fulfillment fees.

    No
    includeCODFulfillmentPreview

    Specifies whether to return fulfillment order previews that are for COD (Cash On Delivery).

    Possible values:

    • true - Returns all fulfillment order previews (both for COD and not for COD).
    • false - Returns only fulfillment order previews that are not for COD. Only applicable for orders in Japan.

    Type: boolean

    No
    includeDeliveryWindows

    Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The ScheduledDeliveryInfo response object can only be returned for fulfillment order previews with ShippingSpeedCategories = ScheduledDelivery. Only applicable for orders in Japan.

    Type: boolean

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type: < FeatureSettings > array

    No

    Request example

    POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview"
     
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "address": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Alexandria",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "items": [
        {
          "sellerSku": "LT205BTBLKAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
          "quantity": 2
        }
      ],
      "featureConstraints": [
        {
          "featureName": "BLANK_BOX",
          "featureFulfillmentPolicy": "Required"
        },
        {
          "featureName": "BLOCK_AMZL",
          "featureFulfillmentPolicy": "Required"
        }
      ],
      "shippingSpeedCategories": [
        "Standard"
      ]
    }
     
    

    Response

    A successful response has a code of 200, and the response schema for the getFulfillmentPreview operation.

    Response example

    {
      "payload": {
        "fulfillmentPreviews": [
          {
            "shippingSpeedCategory": "Standard",
            "isFulfillable": true,
            "isCODCapable": false,
            "estimatedShippingWeight": {
              "unit": "POUNDS",
              "value": "0.441"
            },
            "estimatedFees": [
              {
                "name": "FBAPerOrderFulfillmentFee",
                "amount": {
                  "currencyCode": "USD",
                  "value": "0.0"
                }
              },
              {
                "name": "FBATransportationFee",
                "amount": {
                  "currencyCode": "USD",
                  "value": "0.0"
                }
              },
              {
                "name": "FBAPerUnitFulfillmentFee",
                "amount": {
                  "currencyCode": "USD",
                  "value": "10.31"
                }
              }
            ],
            "fulfillmentPreviewShipments": [
              {
                "earliestShipDate": "2022-12-13T08:00:00Z",
                "latestShipDate": "2022-12-14T07:59:59Z",
                "earliestArrivalDate": "2022-12-15T08:00:00Z",
                "latestArrivalDate": "2022-12-16T07:59:59Z",
                "fulfillmentPreviewItems": [
                  {
                    "sellerSku": "LT205BTBLKAM",
                    "quantity": 2,
                    "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
                    "estimatedShippingWeight": {
                      "unit": "POUNDS",
                      "value": "0.379"
                    },
                    "shippingWeightCalculationMethod": "Dimensional"
                  }
                ]
              }
            ],
            "unfulfillablePreviewItems": [],
            "marketplaceId": "ATVPDKIKX0DER"
          }
        ]
      }
    }
    
    NameDescription
    FulfillmentPreviews

    An array of fulfillment preview information.

    Type: FulfillmentPreviewList

    An unsuccessful response has a code of non-2xx, and includes the objects below. A 404 response will provide the ineligibility errors, if any.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentPreview operation.

    Type: ErrorList

    Yes

    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 will act as a default value, but the value specified in the order request takes priority.

    Body ParameterDescriptionRequired
    marketplaceId

    The marketplace the fulfillment order is placed against.

    Type: string

    No
    sellerFulfillmentOrderId

    A fulfillment order identifier that the seller creates to track their fulfillment order. The sellerFulfillmentOrderId must be unique for each fulfillment order that a seller creates. If the seller's system already creates unique order identifiers, then these might be good values for them to use.

    maxLength : 40

    Type: string

    Yes
    displayableOrderId

    A fulfillment order identifier that the seller creates. This value displays as the order identifier in recipient-facing materials such as the outbound shipment packing slip. The value of `DisplayableOrderId` should match the order identifier that the seller provides to the recipient. The seller can use the SellerFulfillmentOrderId for this value or they can specify an alternate value if they want the recipient to reference an alternate order identifier. The value must be an alpha-numeric or ISO 8859-1 compliant string from one to 40 characters in length. Cannot contain two spaces in a row. Leading and trailing white space is removed.

    maxLength : 40

    Type: string

    Yes
    displayableOrderDate

    The date and time of the fulfillment order. Displays as the order date in recipient-facing materials such as the outbound shipment packing slip.

    Type: Timestamp

    Yes
    displayableOrderComment

    Order-specific text that appears in recipient-facing materials such as the outbound shipment packing slip.

    maxLength : 250

    Type: string

    Yes
    shippingSpeedCategory

    The shipping method for the fulfillment order. Type: ShippingSpeedCategory

    Yes
    deliveryWindow

    The time range within which a Scheduled Delivery fulfillment order should be delivered.

    Type: DeliveryWindow

    No
    destinationAddress

    The destination address for the fulfillment order. Type: Address

    Yes
    fulfillmentAction

    Specifies whether the fulfillment order should ship now or have an order hold put on it.

    Type: FulfillmentAction

    No
    fulfillmentPolicy

    The FulfillmentPolicy value specified when you submitted the createFulfillmentOrder operation.

    Type: FulfillmentPolicy

    No
    codSettings

    The COD (Cash On Delivery) charges that you associate with a COD fulfillment order.

    Type: CODSettings

    No
    shipFromCountryCode

    The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. It is Required if doing a cross border shipment.

    Type: string

    No
    notificationEmails

    A list of email addresses that the seller provides that are used by Amazon to send ship-complete notifications to recipients on behalf of the seller.

    Type: NotificationEmailList

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type:< FeatureSettings > array

    No
    Items

    A list of items to include in the fulfillment order preview, including quantity.

    Type: CreateFulfillmentOrderItemList

    Yes

    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": "Priority",
      "fulfillmentAction": "Ship",
      "destinationAddress": {
        "name": "Mary Major",
        "addressLine1": "123 Any Street",
        "city": "Alexandria",
        "stateOrRegion": "VA",
        "countryCode": "US",
        "postalCode": "22308"
      },
      "items": [
        {
          "sellerSku": "LT205BTBLKAM",
          "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
          "quantity": 1
        }
      ],
      "featureConstraints": [
        {
          "featureName": "BLANK_BOX",
          "featureFulfillmentPolicy": "Required"
        },
        {
          "featureName": "BLOCK_AMZL",
          "featureFulfillmentPolicy": "Required"
        }
      ]
    }
    
    

    Response

    A successful response has a code of 200, and includes the objects below.

    Response example

    {}
    

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescription
    errors

    One or more unexpected errors occurred during the createFulfillmentOrder operation.

    Type: ErrorList

    Step 3. Get the fulfillment order to validate order details

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

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created

    maxLength : 40

    Type: string

    Yes

    Request example

    GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"
    

    Response

    A successful response has a code of 200 with a payload.

    Response example

    {
     "payload": {
       "fulfillmentOrder": {
         "sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
         "marketplaceId": "ATVPDKIKX0DER",
         "displayableOrderId": "CONSUMER-2022921-145045",
         "displayableOrderDate": "2022-01-09T19:46:45.809Z",
         "displayableOrderComment": "TestOrder",
         "shippingSpeedCategory": "Priority",
         "destinationAddress": {
           "name": "Mary Major",
           "addressLine1": "123 Any Street",
           "city": "Alexandria",
           "stateOrRegion": "VA",
           "countryCode": "US",
           "postalCode": "22308"
         },
         "fulfillmentAction": "Ship",
         "fulfillmentPolicy": "FillAllAvailable",
         "receivedDate": "2022-09-21T14:50:45Z",
         "fulfillmentOrderStatus": "Received",
         "statusUpdatedDate": "2022-09-22T03:44:35Z",
         "notificationEmails": [
           "[email protected]"
         ],
         "featureConstraints": [
           {
             "featureName": "BLANK_BOX",
             "featureFulfillmentPolicy": "Required"
           },
           {
             "featureName": "BLOCK_AMZL",
             "featureFulfillmentPolicy": "Required"
           }
         ]
       },
       "fulfillmentOrderItems": [
         {
           "sellerSku": "LT205BLKAM",
           "sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
           "quantity": "1",
           "perUnitDeclaredValue": {
             "currencyCode": "USD",
             "value": "0.00"
           }
         }
       ],
       "fulfillmentShipments": [],
       "returnItems": [],
       "returnAuthorizations": []
     }
    }
    
    Body ParameterDescriptionRequired
    fulfillmentOrder

    General information about a fulfillment order, including its status.

    Type: FulfillmentOrder

    Yes
    fulfillmentOrderItems

    An array of fulfillment order item information.

    Type: FulfillmentOrderItemList

    Yes
    fulfillmentShipments

    An array of fulfillment shipment information.

    Type: FulfillmentShipmentList

    No
    returnItems

    An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

    Type: ReturnItemList

    Yes
    returnAuthorizations

    An array of return authorization information.

    Type: ReturnAuthorizationList

    Yes

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentOrder operation.

    Type: ErrorList

    Yes

    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 will show preview details of all ship speeds.

    Prerequisites

    To complete this tutorial you will need:

    1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
    2. The Amazon Fulfillment role assigned to your developer profile.
    3. The Amazon Fulfillment role selected in the App registration page for your application.

    Step 1. Get the fulfillment preview for all ship speeds

    To retrieve preview details of an order for all ship speeds, skip the attribute shippingCategories in the request to retrieve preview details for all ship speeds.

    Call the getFulfillmentPreview operation by passing the following body parameters:

    Body ParameterDescriptionRequired
    marketplaceId

    The marketplace the fulfillment order is placed against.

    Type: string

    No
    address

    The destination address for the fulfillment order preview.

    Type: Address

    Yes
    items

    Identifying information and quantity information for the items in the fulfillment order preview.

    Type: GetFulfillmentPreviewItemList

    Yes
    shippingSpeedCategories

    A list of shipping methods used for creating fulfillment order previews.

    Possible Values:

    • Standard - Standard shipping method.
    • Expedited - Expedited shipping method.
    • Priority - Priority shipping method.
    • ScheduledDelivery - Scheduled Delivery shipping method only for Japan.

    Note: Shipping method service level agreements vary by marketplace. Sellers should see the Seller Central website in their marketplace for shipping method service level agreements and fulfillment fees.

    No
    includeCODFulfillmentPreview

    Specifies whether to return fulfillment order previews that are for COD (Cash On Delivery).

    Possible values:

    • true - Returns all fulfillment order previews (both for COD and not for COD).
    • false - Returns only fulfillment order previews that are not for COD. Only applicable for orders in Japan.

    Type: boolean

    No
    includeDeliveryWindows

    Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The ScheduledDeliveryInfo response object can only be returned for fulfillment order previews with ShippingSpeedCategories = ScheduledDelivery. Only applicable for orders in Japan.

    Type: boolean

    No
    featureConstraints

    A list of features and their fulfillment policies to apply to the order.

    Type: < FeatureSettings >

    No

    Request example

    POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview"
    
    {
      "marketplaceId": "ATVPDKIKX0DER",
      "address": {
        "name": "Amazon",
        "addressLine1": "123 Any Street",
        "addressLine2": "Building2010",
        "addressLine3": "Lane1",
        "stateOrRegion": "MI",
        "countryCode": "US",
        "country": "US",
        "city": "Troy",
        "postalCode": "48084",
        "phone": "480-441-2465"
      },
      "items": [
        {
          "quantity": 5,
          "sellerFulfillmentOrderItemId": "04740712772466",
          "sellerSku": "LT205BLKAM"
        }
      ],
      "featureConstraints": [
        {
          "featureName": "BLANK_BOX",
          "featureFulfillmentPolicy": "NotRequired"
        },
        {
          "featureName": "BLOCK_AMZL",
          "featureFulfillmentPolicy": "Required"
        }
      ]
    }
    

    Response example

    A successful response has a code of 200, and the response schema for the getFulfillmentPreview operation.

    {
      "payload": {
        "fulfillmentPreviews": [
          {
            "estimatedFees": [
              {
                "amount": {
                  "currencyCode": "USD",
                  "value": "10"
                },
                "name": "FBAPerUnitFulfillmentFee"
              }
            ],
            "estimatedShippingWeight": {
              "unit": "POUNDS",
              "value": "37.55115842140852"
            },
            "featureConstraints": [
              {
                "featureFulfillmentPolicy": "NotRequired",
                "featureName": "BLANK_BOX"
              },
              {
                "featureFulfillmentPolicy": "Required",
                "featureName": "BLOCK_AMZL"
              }
            ],
            "fulfillmentPreviewShipments": [
              {
                "earliestArrivalDate": "2022-12-11T20:35:15Z",
                "earliestShipDate": "2022-12-09T20:35:15Z",
                "fulfillmentPreviewItems": [
                  {
                    "estimatedShippingWeight": {
                      "unit": "POUNDS",
                      "value": "13.44454399298887"
                    },
                    "quantity": 5,
                    "sellerFulfillmentOrderItemId": "04740712772466",
                    "sellerSku": "LT205BLKAM",
                    "shippingWeightCalculationMethod": "Package"
                  }
                ],
                "latestArrivalDate": "2022-12-12T20:35:15Z",
                "latestShipDate": "2022-12-10T20:35:15Z",
                "shippingNotes": []
              }
            ],
            "isCodCapable": false,
            "isFulfillable": true,
            "marketplaceId": "ATVPDKIKX0DER",
            "orderUnfulfillableReasons": [],
            "shippingSpeedCategory": "Standard",
            "unfulfillablePreviewItems": []
          },
          {
            "estimatedFees": [
              {
                "amount": {
                  "currencyCode": "USD",
                  "value": "25"
                },
                "name": "FBAPerUnitFulfillmentFee"
              }
            ],
            "estimatedShippingWeight": {
              "unit": "POUNDS",
              "value": "13.005463669980378"
            },
            "featureConstraints": [
              {
                "featureFulfillmentPolicy": "NotRequired",
                "featureName": "BLANK_BOX"
              },
              {
                "featureFulfillmentPolicy": "Required",
                "featureName": "BLOCK_AMZL"
              }
            ],
            "fulfillmentPreviewShipments": [
              {
                "earliestArrivalDate": "2022-12-09T20:35:15Z",
                "earliestShipDate": "2022-12-08T20:35:15Z",
                "fulfillmentPreviewItems": [
                  {
                    "estimatedShippingWeight": {
                      "unit": "POUNDS",
                      "value": "6.396357461045615"
                    },
                    "quantity": 5,
                    "sellerFulfillmentOrderItemId": "04740712772466",
                    "sellerSku": "LT205BLKAM",
                    "shippingWeightCalculationMethod": "Package"
                  }
                ],
                "latestArrivalDate": "2022-12-10T20:35:15Z",
                "latestShipDate": "2022-12-09T20:35:15Z",
                "shippingNotes": []
              }
            ],
            "isCodCapable": false,
            "isFulfillable": true,
            "marketplaceId": "ATVPDKIKX0DER",
            "orderUnfulfillableReasons": [],
            "shippingSpeedCategory": "Expedited",
            "unfulfillablePreviewItems": []
          },
          {
            "estimatedFees": [
              {
                "amount": {
                  "currencyCode": "USD",
                  "value": "10"
                },
                "name": "FBAPerUnitFulfillmentFee"
              }
            ],
            "estimatedShippingWeight": {
              "unit": "POUNDS",
              "value": "37.09772884213881"
            },
            "featureConstraints": [
              {
                "featureFulfillmentPolicy": "NotRequired",
                "featureName": "BLANK_BOX"
              },
              {
                "featureFulfillmentPolicy": "Required",
                "featureName": "BLOCK_AMZL"
              }
            ],
            "fulfillmentPreviewShipments": [
              {
                "earliestArrivalDate": "2022-12-08T20:35:15Z",
                "earliestShipDate": "2022-12-07T20:35:15Z",
                "fulfillmentPreviewItems": [
                  {
                    "estimatedShippingWeight": {
                      "unit": "POUNDS",
                      "value": "28.261562502894723"
                    },
                    "quantity": 5,
                    "sellerFulfillmentOrderItemId": "04740712772466",
                    "sellerSku": "LT205BLKAM",
                    "shippingWeightCalculationMethod": "Package"
                  }
                ],
                "latestArrivalDate": "2022-12-09T20:35:15Z",
                "latestShipDate": "2022-12-08T20:35:15Z",
                "shippingNotes": []
              }
            ],
            "isCodCapable": false,
            "isFulfillable": true,
            "marketplaceId": "ATVPDKIKX0DER",
            "orderUnfulfillableReasons": [],
            "shippingSpeedCategory": "Priority",
            "unfulfillablePreviewItems": []
          }
        ]
      }
    }
    
    NameDescription
    FulfillmentPreviews

    An array of fulfillment preview information.

    Type: FulfillmentPreviewList

    An unsuccessful response has a code of non-2xx, and includes the objects below. A 404 response will provide the ineligibility errors, if any.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentPreview operation.

    Type: ErrorList

    Yes

    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 will need:

    1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
    2. The Amazon Fulfillment role assigned to your developer profile.
    3. The Amazon Fulfillment role selected in the App registration page for your application.

    Step 1. Create and subscribe to notifications

    Refer to the Notifications API to create and manage subscriptions.

    Step 2. Listen to order status notifications

    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 once itโ€™s made ready for shipping.

    Response example

    {
      "NotificationVersion": "1.0",
      "NotificationType": "FULFILLMENT_ORDER_STATUS",
      "PayloadVersion": "1.0",
      "EventTime": "2020-07-13T19:42:04.284Z",
      "Payload": {
        "FulfillmentOrderStatusNotification": {
          "SellerId": "A3TH9S8BH6GOGM",
          "EventType": "Order",
          "StatusUpdatedDateTime": "2020-07-13T19:42:04.284Z",
          "SellerFulfillmentOrderId": "amazonbooks.KLA1.202203072322.6911",
          "FulfillmentOrderStatus": "Complete",
          "FulfillmentShipment": {
            "FulfillmentShipmentStatus": "Shipped",
            "AmazonShipmentId": "ASID49535",
            "EstimatedArrivalDateTime": "2020-07-13T19:42:04.284Z",
            "FulfillmentShipmentPackages": [
              {
                "PackageNumber": 1,
                "CarrierCode": "2-930434",
                "TrackingNumber": "1Z84456456573405"
              },
              {
                "PackageNumber": 2,
                "CarrierCode": "1-930434",
                "TrackingNumber": "1Z84456456573405"
              },
              {
                "PackageNumber": 3,
                "CarrierCode": "3-930434",
                "TrackingNumber": "1Z885647654573405"
              }
            ]
          },
          "FulfillmentReturnItem": {
            "ReceivedDateTime": "2020-07-13T19:42:04.284Z",
            "ReturnedQuantity": 12,
            "SellerSKU": "SELLERSKU9345"
          }
        }
      },
      "NotificationMetadata": {
        "ApplicationId": "app-id-d0e9e693-c3ad-4373-979f-ed4ec98dd746",
        "SubscriptionId": "subscription-id-d0e9e693-c3ad-4373-979f-ed4ec98dd746",
        "PublishTime": "2020-07-13T19:42:04.284Z",
        "NotificationId": "d0e9e693-c3ad-4373-979f-ed4ec98dd746"
      }
    }
    
    Body ParameterDescriptionRequired
    EventType

    Indicates whether the notification contains order, shipment, or return information.

    EventType values:

    • Order - This notification contains information about a fulfillment order.
    • Shipment - This notification contains information about a fulfillment shipment. For more information, see the FulfillmentShipment object.
    • Return - This notification contains information about a fulfillment return.

    Type: string

    Yes
    SellerId

    The identifier of the seller.

    Type: string

    No
    StatusUpdatedDateTime

    The date and time when the status was last updated. In ISO 8601 format.

    Type: string

    Yes
    SellerFulfillmentOrderId

    The fulfillment order identifier that you created and submitted using the CreateFulfillmentOrder operation.

    Type: string

    Yes
    FulfillmentOrderStatus

    The current status of the fulfillment order.

    FulfillmentOrderStatus values:

    • Received - The fulfillment order was received and validated. Validation includes determining that the destination address is valid and that Amazon's records indicate that the seller has enough sellable (undamaged) inventory to fulfill the order. The seller can cancel a fulfillment order that has a status of Received.
    • Invalid - The fulfillment order was received but could not be validated. The reasons for this include an invalid destination address or Amazon's records indicating that the seller does not have enough sellable inventory to fulfill the order. When this happens, the fulfillment order is invalid and no items in the order will ship.
    • Planning - The fulfillment order has been sent to Amazon's fulfillment network to begin shipment planning, but no unit in any shipment has been picked from inventory yet. The seller can cancel a fulfillment order that has a status of Planning.
    • Processing - The process of picking units from inventory has begun on at least one shipment in the fulfillment order. The seller cannot cancel a fulfillment order that has a status of Processing.
    • Cancelled - The fulfillment order has been cancelled by the seller.
    • Complete - All item quantities in the fulfillment order have been fulfilled.
    • CompletePartialled - Some item quantities in the fulfillment order were fulfilled; the rest were either cancelled or unfulfillable.
    • Unfulfillable - No item quantities in the fulfillment order could be fulfilled because the Amazon fulfillment center workers found no inventory for those items or found no inventory that was in sellable (undamaged) condition.

    Type: string

    Yes
    FulfillmentShipment

    Delivery and item information for a shipment in a fulfillment order.

    Type: FulfillmentShipment

    No
    FulfillmentReturnItem

    Information about an item that was returned to an Amazon fulfillment center.

    Type: FulfillmentReturnItem

    No

    Tutorial: Create a return for an MCF order

    MCF order returns are comprised of three steps: getting the return reason codes, submitting the return using one of the codes and finally 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 will need:

    1. Authorization from the selling partner for whom you are making calls. See Authorizing Selling Partner API Applications for more information.
    2. The Amazon Fulfillment role assigned to your developer profile.
    3. The Amazon Fulfillment role selected in the App registration page for your application.

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

    Call the listReturnReasonCodes operation by passing the following parameters:

    ParameterDescriptionRequired
    sellerSKU

    The seller SKU for which return reason codes are required.

    Type: string

    Yes
    marketplaceId

    The marketplace for which the seller wants return reason codes.

    Type: string

    no
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created. The service uses this value to determine the marketplace for which the seller wants return reason codes.

    Type: string

    no
    language

    The language that the TranslatedDescription property of the ReasonCodeDetails response object should be translated into.

    Type: string

    Yes

    Request example

    GET https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/returnReasonCodes?sellerSku=LT205BLKAM&marketplaceId=ATVPDKIKX0DER&sellerFulfillmentOrderId=CONSUMER-2022921-1450456&language=EN
    

    Response

    A successful response has a code of 200.

    Response example

    {
      "payload": {
        "ReasonCodeDetailsList": [
          {
            "ReturnReasonCode": "CR-SWITCHEROO",
            "Description": "Different from what was ordered",
            "TranslatedDescription": "Product does not meet customer expectations"
          },
          {
            "ReturnReasonCode": "CR-DAMAGED_BY_CARRIER",
            "Description": "Damaged during shipping"
          },
          {
            "ReturnReasonCode": "CR-UNAUTHORIZED_PURCHASE",
            "Description": "Unauthorized purchase"
          },
          {
            "ReturnReasonCode": "CR-UNWANTED_ITEM",
            "Description": "No longer needed/wanted",
            "TranslatedDescription": "Unwanted item"
          },
          {
            "ReturnReasonCode": "CR-MISSED_ESTIMATED_DELIVERY",
            "Description": "Missed estimated delivery date"
          },
          {
            "ReturnReasonCode": "CR-FOUND_BETTER_PRICE",
            "Description": "Better price available",
            "TranslatedDescription": "I found better prices elsewhere"
          },
          {
            "ReturnReasonCode": "CR-MISSING_PARTS",
            "Description": "Missing parts or accessories"
          },
          {
            "ReturnReasonCode": "CR-EXTRA_ITEM",
            "Description": "Arrived in addition to what was ordered",
            "TranslatedDescription": "Extra item included in shipment"
          },
          {
            "ReturnReasonCode": "CR-ORDERED_WRONG_ITEM",
            "Description": "Accidental order"
          },
          {
            "ReturnReasonCode": "AMZ-PG-BAD-DESC",
            "Description": "Different from website description"
          },
          {
            "ReturnReasonCode": "CR-DAMAGED_BY_FC",
            "Description": "Damaged due to inappropriate packaging",
            "TranslatedDescription": "Product damaged or defective prior to shipping"
          },
          {
            "ReturnReasonCode": "CR-DEFECTIVE",
            "Description": "Defective/Does not work properly",
            "TranslatedDescription": "Item is defective"
          }
        ]
      }
    }
    
    NameDescriptionRequired
    returnReasonCode

    A code that indicates a valid return reason.

    Type: string

    Yes
    description

    A human readable description of the return reason code.

    Type: string

    Yes
    translatedDescription

    A translation of the description. The translation is in the language specified in the Language request parameter.

    Type: string

    No

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescription
    errors

    One or more unexpected errors occurred during the listReturnReasonCodes operation.

    Type: ErrorList

    Step 2. Create a fulfillment return for an order

    Using one of the reasons fetched in the above step, make a call to the createFulfillmentReturn operation to submit the return request and fetch the return shipping label needed to ship the item to Amazon.

    ๐Ÿ“˜

    Non-prepaid label

    This label is not prepaid. It needs to be paid by the shipping person.

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    An identifier assigned by the seller to the fulfillment order at the time it was created. The seller uses their own records to find the correct sellerFulfillmentOrderId value based on the buyer's request to return items.

    Type: string

    Yes
    Body ParameterDescriptionRequired
    sellerReturnItemId

    An identifier assigned by the seller to the return item.

    Type: string

    Yes
    sellerFulfillmentOrderItemId

    The identifier assigned to the item by the seller when the fulfillment order was created.

    Type: string

    Yes
    amazonShipmentId

    The identifier for the shipment that is associated with the return item.

    Type: string

    Yes
    returnReasonCode

    The return reason code assigned to the return item by the seller.

    Type: string

    Yes
    returnComment

    An optional comment about the return item.

    Type: string

    No

    Request example

    PUT "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/fc5d0aaf64e6d9d517fa7572c0/return"
     
    {
      "items": [
        {
          "sellerReturnItemId": "Itm1",
          "sellerFulfillmentOrderItemId": "fc5d0aaf64e6d9d517fa7572c0",
          "amazonShipmentId": "Uvwxq86C7",
          "returnReasonCode": "CR-ORDERED_WRONG_ITEM",
          "returnComment": "Accidental order"
        }
      ]
    }
    

    Response

    A successful response has a code of 200, and the response schema for the createFulfillmentReturn operation.

    Response example

    {
      "payload": {
        "returnItems": [
          {
            "sellerReturnItemId": "Itm1",
            "sellerFulfillmentOrderItemId": "fc5d0aaf64e6d9d517fa7572c0",
            "amazonShipmentId": "Uvwxq86C7",
            "returnComment": "Accidental order",
            "amazonReturnReasonCode": "CR-ORDERED_WRONG_ITEM",
            "status": "New",
            "statusChangedDate": "2022-10-26T03:48:29Z",
            "returnAuthorizationId": "RMA26PCEUDROQE18"
          }
        ],
        "invalidReturnItems": [],
        "returnAuthorizations": [
          {
            "returnAuthorizationId": "RMA26PCEUDROQE18",
            "fulfillmentCenterId": "LEX2",
            "returnToAddress": {
              "name": "Returns Department",
              "addressLine1": "123 Any Street",
              "districtOrCounty": "US",
              "city": "Lexington",
              "stateOrRegion": "KY",
              "countryCode": "US",
              "postalCode": "40511"
            },
            "amazonRmaId": "DBKKwqJ0RRMA",
            "rmaPageURL": "https://www.amazon.com/spr/returns/label/rmaID/DBKKwqJ0RRMA"
          }
        ]
      }
    }
    
    NameDescriptionRequired
    ReturnItemList

    An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

    Type: < ReturnItem > array

    Yes
    InvalidReturnItemList

    An array of invalid return item information.

    Type: < InvalidReturnItem > array

    Yes
    ReturnAuthorizationList

    An array of return authorization information.

    Type: < ReturnAuthorization > array

    Yes
    NameDescription
    errors

    One or more unexpected errors occurred during the operation.

    Type: ErrorList

    An unsuccessful response has a code of non-2xx, and includes the objects below. A 404 response will provide the ineligibility errors, if any.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the createFulfillmentReturn operation.

    Type: ErrorList

    Yes

    Step 3. Ship the returning item

    From the response above, the rmaPageURL will provide 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

    Once the package is received by 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.

    ParameterDescriptionRequired
    sellerFulfillmentOrderId

    The identifier assigned to the item by the seller when the fulfillment order was created.

    maxLength : 40

    Type: string

    Yes

    Request example

    GET "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-1450456"
    

    Response

    A successful response has a code of 200 with a payload.

    Response example

    {
      "payload": {
        "fulfillmentOrder": {
          "sellerFulfillmentOrderId": "CONSUMER-2022921-1450456",
          "marketplaceId": "ATVPDKIKX0DER",
          "displayableOrderId": "Test Order1",
          "displayableOrderDate": "2022-10-31T15:15:20Z",
          "displayableOrderComment": "We have received your Order.",
          "shippingSpeedCategory": "Standard",
          "destinationAddress": {
            "name": "Nikki Wolf",
            "addressLine1": "123 Any Street",
            "city": "Charlotte",
            "stateOrRegion": "NC",
            "countryCode": "US",
            "postalCode": "28277"
          },
          "fulfillmentAction": "Ship",
          "fulfillmentPolicy": "FillAllAvailable",
          "receivedDate": "2022-10-31T13:24:13Z",
          "fulfillmentOrderStatus": "Complete",
          "statusUpdatedDate": "2022-11-07T15:14:04Z",
          "featureConstraints": [
            {
              "featureName": "BLANK_BOX",
              "featureFulfillmentPolicy": "Required"
            },
            {
              "featureName": "BLOCK_AMZL",
              "featureFulfillmentPolicy": "Required"
            }
          ]
        },
        "fulfillmentOrderItems": [
          {
            "sellerSku": "LT205BLKAM",
            "sellerFulfillmentOrderItemId": "fc5d0aaf64e6d9d517fa7572c0",
            "quantity": "1",
            "fulfillmentNetworkSku": "X002ZKYQ4Z",
            "orderItemDisposition": "Sellable",
            "cancelledQuantity": "0",
            "unfulfillableQuantity": "0",
            "estimatedShipDate": "2022-11-01T06:59:59Z",
            "estimatedArrivalDate": "2022-11-05T06:59:59Z",
            "perUnitDeclaredValue": {
              "currencyCode": "USD",
              "value": "1995.00"
            }
          }
        ],
        "fulfillmentShipments": [
          {
            "amazonShipmentId": "Uvwxq86C7",
            "fulfillmentCenterId": "GYR1",
            "fulfillmentShipmentStatus": "SHIPPED",
            "shippingDate": "2022-10-31T21:16:36Z",
            "estimatedArrivalDate": "2022-11-05T06:59:59Z",
            "fulfillmentShipmentItem": [
              {
                "sellerSku": "LT205BLKAM",
                "sellerFulfillmentOrderItemId": "16653",
                "quantity": "1",
                "packageNumber": "1725289037"
              }
            ],
            "fulfillmentShipmentPackage": [
              {
                "packageNumber": "UA-123456789",
                "carrierCode": "UPS",
                "trackingNumber": "1Z62Y7Y8425779999",
                "estimatedArrivalDate": "2022-11-05T03:00:00Z"
              }
            ]
          }
        ],
        "returnItems": [
          {
            "amazonShipmentId": "Uvwxq86C7",
            "sellerFulfillmentOrderItemId": "fc5d0aaf64e6d9d517fa7572c0",
            "sellerReturnItemId": "SRII1",
            "returnComment": "recomment",
            "amazonReturnReasonCode": "CR-ORDERED_WRONG_ITEM",
            "status": "New",
            "statusChangedDate": "2022-11-07T23:14:01Z",
            "returnAuthorizationId": "RMA26PCEUDROQE18"
          }
        ],
        "returnAuthorizations": [
          {
            "returnAuthorizationId": "RMA26PCEUDROQE18",
            "fulfillmentCenterId": "LAS2",
            "returnToAddress": {
              "name": "Returns Department",
              "addressLine1": "100 Main Street",
              "addressLine2": "Ste 111",
              "districtOrCounty": "US",
              "city": "Las Vegas",
              "stateOrRegion": "NV",
              "countryCode": "US",
              "postalCode": "89193"
            },
            "amazonRmaId": "D2dJ2rJ6RRMA",
            "rmaPageURL": "https://www.amazon.com/spr/returns/label/rmaID/D2dJ2rJ6RRMA"
          }
        ]
      }
    }
    
    Body ParameterDescriptionRequired
    fulfillmentOrder

    General information about a fulfillment order, including its status.

    Type: FulfillmentOrder

    Yes
    fulfillmentOrderItems

    An array of fulfillment order item information.

    Type: FulfillmentOrderItemList

    Yes
    fulfillmentShipments

    An array of fulfillment shipment information.

    Type: FulfillmentShipmentList

    No
    returnItems

    An array of items that Amazon accepted for return. Returns empty if no items were accepted for return.

    Type: ReturnItemList

    Yes
    returnAuthorizations

    An array of return authorization information.

    Type: ReturnAuthorizationList

    Yes

    An unsuccessful response has a code of non-2xx, and includes the objects below.

    NameDescriptionRequired
    errors

    One or more unexpected errors occurred during the getFulfillmentOrder operation.

    Type: ErrorList

    Yes