Fulfillment Outbound API v2020-07-01 Use Case Guide
How to use the Fulfillment Outbound API.
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
To complete the tutorials, you need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
-
The Amazon Fulfillment role assigned to your developer profile.
-
The Amazon Fulfillment role selected in the App registration page for your application.
Tutorial: Retrieve proof of delivery for a delivered package
Learn how to get the photo or signature for a delivered Multi-Channel Fulfillment Outbound shipment.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Get proof of delivery
Call the getFulfillmentOrder operation by passing the following parameters:
Path parameters
| Name | Description | Required |
|---|---|---|
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
| Name | Description | Required |
|---|---|---|
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 |
Response example
{
"payload": {
"fulfillmentOrder": {
"sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
"marketplaceId": "ATVPDKIKX0DER",
"displayableOrderId": "CONSUMER-2022921-145045",
"displayableOrderDate": "2024-05-21T14:48:15Z",
"displayableOrderComment": "Thank you for your order",
"shippingSpeedCategory": "Standard",
"destinationAddress": {
"name": "Jane Smith",
"addressLine1": "123 Any Street",
"city": "Any Town",
"stateOrRegion": "NC"
"countryCode": "US",
"postalCode": "28277"
},
"fulfillmentAction": "Ship",
"fulfillmentPolicy": "FillAllAvailable",
"receivedDate": "2024-05-21T14:50:45Z",
"fulfillmentOrderStatus": "CompletePartialled",
"statusUpdatedDate": "2024-05-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": "2024-05-22T06:59:59Z",
"estimatedArrivalDate": "2024-05-26T06:59:59Z",
"perUnitDeclaredValue": {
"currencyCode": "USD",
"value": "35.00"
}
},
],
"fulfillmentShipments": [
{
"amazonShipmentId": "T7mfkbDX5",
"fulfillmentCenterId": "TUL2",
"fulfillmentShipmentStatus": "SHIPPED",
"shippingDate": "2024-05-22T03:39:19Z",
"estimatedArrivalDate": "2024-05-26T06:59:59Z",
"fulfillmentShipmentItem": [
{
"sellerSku": "LT205BLKAM",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
"quantity": "1",
"packageNumber": "1681854637"
}
],
"fulfillmentShipmentPackage": [
{
"packageNumber": "1681854637",
"carrierCode": "AMZL",
"trackingNumber": "TBA123456789012",
"estimatedArrivalDate": "2024-05-26T06:59:59Z",
"deliveryInformation": {
"deliveryDocumentList": [
{
"documentType" : "DELIVERY_IMAGE",
"url" : "https://some-image-url.com"
}
],
"dropOffLocation": {
"type" : "FRONT_DOOR"
}
}
}
],
"returnItems": [],
"returnAuthorizations": []
}
}
Tutorial: Retrieve a list of fulfillment orders
This tutorial shows you how to get a list of fulfillment orders after (or at) a specific date-time, or indicated by the next token parameter.
Prerequisites
To complete this tutorial, you need:
-
Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
-
The Amazon Fulfillment role assigned to your developer profile.
-
The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a list of all fulfillment orders
Call the listAllFulfillmentOrders operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
queryStartDate | A date that you can use 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 retrieving 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 200 code.
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"
}
]
}
]
}
}
| Name | Description | Required |
|---|---|---|
sellerFulfillmentOrderId | The fulfillment order identifier submitted with the 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 Type: string | Yes |
displayableOrderDate | A date and time submitted with the Type: | Yes |
displayableOrderComment | A text block submitted with the Type: string | Yes |
shippingSpeedCategory | The shipping method used for the fulfillment order. Type: | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address submitted with the Type: | Yes |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The cash on delivery (COD) charges that you associate with a COD fulfillment order. Type: | No |
receivedDate | The date and time that the fulfillment order was received by an Amazon fulfillment center. Type: | Yes |
fulfillmentOrderStatus | The current status of the fulfillment order. Type: | Yes |
statusUpdatedDate | The date and time that the status of the fulfillment order last changed, in ISO 8601 date-time format. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the operation. Type: |
Tutorial: Retrieve delivery tracking information
This tutorial shows you how to get delivery tracking information for a package in an outbound shipment for a Multi-Channel Fulfillment order.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get the package tracking details
Call the getPackageTrackingDetails operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
packageNumber | The package identifier returned by the 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",
"deliveryWindow": {
"earliest": "2019-10-13T20:53:49Z",
"latest": "2019-10-15T12:40:29Z"
},
"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 non-2xx code and includes the following objects. If the PackageNumber does not exist, a 404 response provides the ineligibility errors.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Cancel a fulfillment order
This tutorial shows you how to send a request to Amazon to stop attempts to fulfill a fulfillment order indicated by the specified order identifier for a given marketplace. The cancelFulfillmentOrder operation should only be called when the order is in 'Received' or 'Planning' status.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Cancel a fulfillment order
Call the cancelFulfillmentOrder operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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 non-2xx code and includes the following objects. If the sellerFulfillmentOrderId does not exist, a 404 response provides the ineligibility errors.
| Name | Description |
|---|---|
| errors | One or more unexpected errors occurred during the Type: |
Tutorial: Retrieve a list of features
This tutorial shows you how to get a list of features available for Multi-Channel Fulfillment orders in the marketplace you specify, and whether the seller for which you made the call is enrolled for each feature.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a list of features
Call the getFeatures operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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 200 code.
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
}
]
}
| Parameter | Description | Required |
|---|---|---|
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 non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Retrieve inventory eligible for Blank Box
This tutorial shows you how to get a list of inventory items that are eligible for Blank Box.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a list of feature inventory items
Call the getFeatureInventory operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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 Type: string | No |
queryStartDate | A date used to select inventory that has been last updated after (or at), up to 90 days ago. An update is defined as any change in feature enabled inventory availability. This must be in yyyy-MM-ddTHH:mm:ss.sssZ format, for example: 2020-04-04T16:20:23.000Z. Type: string (date-time) | 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 200 code.
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": []
}
]
}
}
| Parameter | Description | Required |
|---|---|---|
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: < | No |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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
sellerSKUIf the
sellerSKUisn't eligible, the response contains an emptyskuInfoobject.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a count of feature Seller SKUs
Call the getFeatureSKU operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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. 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"
}
}
| Parameter | Description | Required |
|---|---|---|
marketplaceId | The requested marketplace. Type: string | Yes |
| The name of the feature. Type: string | Yes |
isEligible | When true, the seller Type: Boolean | Yes |
ineligibleReasons | A list of one or more reasons that the seller SKU is ineligible for the feature. Possible values:
Type: < string > array | No |
skuInfo | Information about the Type: | No |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Create a Japan order with scheduled delivery and delivery time windows
This tutorial outlines the order creation process for Japan with the scheduled delivery shipping option. This ship option is only available for Japan marketplace orders.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get the fulfillment preview for scheduled delivery dates
Call the getFulfillmentPreview operation with values ShippingSpeedCategories = ScheduledDelivery and IncludeDeliveryWindows = true.
| Body Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. Type: string | No |
address | The destination address for the fulfillment order preview. Type: | Yes |
items | Identifying information and quantity information for the items in the fulfillment order preview. | Yes |
shippingSpeedCategories | A list of shipping methods used for creating fulfillment order previews. Possible values:
Note: Shipping method service-level agreements vary by marketplace. Sellers should refer to 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 cash on delivery (COD). Possible values:
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 Type: Boolean | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Request example
POST "https://sellingpartnerapi-fe.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview"
{
"marketplaceId": "A1VC38T7YXB528",
"address": {
"name": "Mary Major",
"addressLine1": "1-8-1 Shimomeguro",
"addressLine2": "Meguro-ku",
"city": "Tokyo",
"countryCode": "JP",
"postalCode": "153-0064"
},
"items": [
{
"sellerSku": "SellerSKU12",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
"quantity": 2
}
],
"shippingSpeedCategories": [
"ScheduledDelivery"
],
"IncludeDeliveryWindows": "true"
}
Response
A successful response has a 200 code and the response schema for the getFulfillmentPreview operation.
{
"payload": {
"fulfillmentPreviews": [
{
"shippingSpeedCategory": "ScheduledDelivery",
"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"
}
]
}
],
"scheduledDeliveryinfo": {
"deliveryTimeZone": "UTC",
"deliveryWindows": [
{
"endDate": "2022-12-15T10:48:11Z",
"startDate": "2022-12-15T06:48:11Z"
},
{
"endDate": "2022-12-16T14:48:11Z",
"startDate": "2022-12-16T10:48:11Z"
}
]
},
"unfulfillablePreviewItems": [],
"marketplaceId": "A1VC38T7YXB528"
}
]
}
}
| Name | Description |
|---|---|
FulfillmentPreviews | An array of fulfillment preview information. Type: |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the operation. Type: |
Step 2. Create a fulfillment order
Call the createFulfillmentOrder operation with the Delivery Window obtained from the getFulfillmentPreview response and with ShippingSpeedCategory = ScheduledDelivery. If you use any other window with the createFulfillmentOrder operation, the service returns an error and you must rerun the getFulfillmentPreview operation.
Note
Shipping method service-level agreements vary by marketplace. Sellers can refer to Seller Central for shipping method service-level agreements and multi-channel fulfillment fees.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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. ShippingSpeedCategory | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The COD charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Items | A list of items to include in the fulfillment order preview, including quantity. | Yes |
Request example
POST "https://sellingpartnerapi-fe.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": {
"endDate": "2022-12-15T10:48:11Z",
"startDate": "2022-12-15T06:48:11Z"
},
"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 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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.
| Parameter | Description | Required |
|---|---|---|
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-fe.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/CONSUMER-2022921-145045"
Response
A successful response has a 200 code 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"
},
"deliveryWindow": {
"endDate": "2022-12-15T10:48:11Z",
"startDate": "2022-12-15T06:48:11Z"
}
"fulfillmentAction": "Ship",
"fulfillmentPolicy": "FillAllAvailable",
"receivedDate": "2022-09-21T14:50:45Z",
"fulfillmentOrderStatus": "Received",
"statusUpdatedDate": "2022-09-22T03:44:35Z"
},
"fulfillmentOrderItems": [
{
"sellerSku": "SellerSKU12",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
"quantity": "1"
}
],
"fulfillmentShipments": [],
"returnItems": [],
"returnAuthorizations": []
}
}
| Body Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
| An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the operation. Type: |
Tutorial: Create an MCF order for India
This tutorial outlines the MCF order creation process for India.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a fulfillment preview
| Body Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. Type: string | No |
address | The destination address for the fulfillment order preview. Type: | Yes |
items | Identifying information and quantity information for the items in the fulfillment order preview. | Yes |
shippingSpeedCategories | A list of shipping methods used for creating fulfillment order previews. Possible values:
Note: Shipping method service-level agreements vary by marketplace. Standard shipping method is the only shipping method supported for India. Sellers should refer to 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 cash on delivery (COD). Possible values:
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 Type: Boolean | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Request example
POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders/preview"
{
"marketplaceId": "A21TJRUUN4KGV",
"address":
{
"name": "Saanvi Sarkar",
"addressLine1": "FLAT#20012, Tower#20, Prestige Ferns Residency, Haralur Road",
"city": "Bengaluru",
"stateOrRegion": "KA",
"countryCode": "IN",
"postalCode": "560021",
"phone": "9986365404"
},
"items": [
{
"sellerSku": "mohamf devogst8 B06XSK3XL6",
"sellerFulfillmentOrderItemId": "OrderItemID1",
"quantity": 1
}
],
"shippingSpeedCategories": [
"Standard"
],
"featureConstraints": [
{
"featureName": "BLANK_BOX",
"featureFulfillmentPolicy": "NOTREQUIRED"
}
]
}
Response
A successful response has a 200 code and the response schema for the getFulfillmentPreview operation.
{
"payload": {
"fulfillmentPreviews": [
{
"shippingSpeedCategory": "Standard",
"isFulfillable": false,
"isCODCapable": false,
"fulfillmentPreviewShipments": [
{
"earliestShipDate": "2023-12-09T10:42:10Z",
"latestShipDate": "2023-12-09T10:42:10Z",
"earliestArrivalDate": "2023-12-11T10:42:10Z",
"latestArrivalDate": "2023-12-13T10:42:10Z",
"fulfillmentPreviewItems": [
{
"sellerSku": "mohamf devogst8 B06XSK3XL6",
"quantity": 1,
"sellerFulfillmentOrderItemId": "OrderItemID1",
"estimatedShippingWeight": {
"unit": "KILOGRAMS",
"value": "0.350"
},
"shippingWeightCalculationMethod": "Package"
}
]
}
],
"marketplaceId": "A21TJRUUN4KGV",
"featureConstraints": [
{
"featureName": "BLANK_BOX",
"featureFulfillmentPolicy": "NotRequired"
}
]
}
]
}
}
| Name | Description |
|---|---|
FulfillmentPreviews | An array of fulfillment preview information. Type: |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the operation. Type: |
Step 2a. Create a fulfillment order
Call the createFulfillmentOrder operation to create an MCF order specifying the feature constraints required for the order.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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. ShippingSpeedCategory | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The COD charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
items | A list of items to include in the fulfillment order preview, including quantity. Maximum of 100 line items with a maximum of 250 units per order. | Yes |
paymentInformation | The payment information for the fulfillment order. Type: | Yes |
Request example
POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders"
{
"sellerFulfillmentOrderId": "createOrder1703154732",
"displayableOrderId": "TestOrder-FBAOutbound20",
"displayableOrderDate": "2023-11-09T19:46:45.809Z",
"displayableOrderComment": "TestOrder",
"shippingSpeedCategory": "Standard",
"fulfillmentAction": "Ship",
"destinationAddress": {
"name": "Anshul R",
"addressLine1": "FLAT#1234, Tower#201, Prestige Residency, Haralur Road",
"city": "Bengaluru",
"stateOrRegion": "KA",
"countryCode": "IN",
"postalCode": "560102",
"phone": "9168071234"
},
"notificationEmails": [
"[email protected]"
],
"items": [
{
"sellerSku": "mohamf devogst8 B06XSK3XL6",
"sellerFulfillmentOrderItemId": "OrderItemID1",
"quantity": 1,
"perUnitDeclaredValue": {
"currencyCode": "INR",
"value": "2.00"
}
}
],
"paymentInformation": [
{
"paymentTransactionId": "TestPaymenttransaction",
"paymentMode": "Other",
"paymentDate": "2023-11-14T16:25:56Z"
}
]
}
Response
A successful response has a 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Step 2b. Create a fulfillment order with a COD option
Call the createFullfillmentOrder operation to create an MCF order with a cash on delivery (COD) option. For COD orders in the IN marketplace, none of the monetary values in codSettings (codCharge, codChargeTax, shippingCharge, shippingChargeTax) should be set. All the charges in the order must be represented with perUnitDeclaredValue.
| Body Parameter | Description | Required |
|---|---|---|
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.max length: 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. max length: 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 |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: DeliveryPreferences | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: FulfillmentAction | No |
fulfillmentPolicy | The fulfillment policy. Type: FulfillmentPolicy | No |
codSettings | The COD charges that you associate with a COD fulfillment order. Note: Only isCodRequired needs to be set. codCharge, codChargeTax, shippingCharge, and shippingChargeTax should not be set for the IN marketplace.Type: CODSettings | Yes |
shipFromCountryCode | The two-character country code for the country from which the fulfillment order ships. Must be in ISO 3166-1 alpha-2 format. This is required for cross-border shipments. 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. Maximum of 100 line items with a maximum of 250 units per order. Type: CreateFulfillmentOrderItemList | Yes |
Request example
POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/fulfillmentOrders"
{
"sellerFulfillmentOrderId": "createOrder1703154732",
"displayableOrderId": "TestOrder-FBAOutbound20",
"displayableOrderDate": "2023-11-09T19:46:45.809Z",
"displayableOrderComment": "TestOrder",
"shippingSpeedCategory": "Standard",
"fulfillmentAction": "Ship",
"destinationAddress": {
"name": "Anshul R",
"addressLine1": "FLAT#1234, Tower#201, Prestige Residency, Haralur Road",
"city": "Bengaluru",
"stateOrRegion": "KA",
"countryCode": "IN",
"postalCode": "560102",
"phone": "9168071234"
},
`"codSettings": {
"isCodRequired": true
},`
"notificationEmails": [
"[email protected]"
],
"items": [
{
"sellerSku": "mohamf devogst8 B06XSK3XL6",
"sellerFulfillmentOrderItemId": "OrderItemID1",
"quantity": 1,
"perUnitDeclaredValue": {
"currencyCode": "INR",
"value": "2.00"
}
}
]
}
Response
A successful response has a 200 code and is empty.
An unsuccessful has a non-2xx code and includes the following objects:
| Name | Description |
|---|---|
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.
| Parameter | Description | Required |
|---|---|---|
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 200 code with a payload.
Response example
{
"payload": {
"fulfillmentOrder": {
"sellerFulfillmentOrderId": "createOrder1703154732",
"marketplaceId": "A2XZLSVIQ0F4JT",
"displayableOrderId": "TestOrder-FBAOutbound20",
"displayableOrderDate": "2023-11-09T19:46:45Z",
"displayableOrderComment": "TestOrder",
"shippingSpeedCategory": "Standard",
"destinationAddress": {
"name": "Anshul R",
"addressLine1": "FLAT#1234, Tower#201, Prestige Residency, Haralur Road",
"city": "Bengaluru",
"stateOrRegion": "KA",
"countryCode": "IN",
"postalCode": "560102",
"phone": "9168071234"
},
"fulfillmentAction": "Ship",
"fulfillmentPolicy": "FillOrKill",
"receivedDate": "2023-12-21T10:32:12Z",
"fulfillmentOrderStatus": "Planning",
"statusUpdatedDate": "2023-12-21T10:32:20Z",
"notificationEmails": [
"[email protected]"
],
"featureConstraints": [
{
"featureName": "BLANK_BOX",
"featureFulfillmentPolicy": "NotRequired"
}
]
},
"fulfillmentOrderItems": [
{
"sellerSku": "mohamf devogst8 B06XSK3XL6",
"sellerFulfillmentOrderItemId": "OrderItemID1",
"quantity": "1",
"fulfillmentNetworkSku": "X0014EAZ4D",
"orderItemDisposition": "Sellable",
"cancelledQuantity": "0",
"unfulfillableQuantity": "0",
"estimatedShipDate": "2023-12-22T18:29:59Z",
"estimatedArrivalDate": "2023-12-26T18:29:59Z",
"perUnitDeclaredValue": {
"currencyCode": "INR",
"value": "2.00"
}
}
],
"fulfillmentShipments": [],
"returnItems": [],
"returnAuthorizations": [],
"paymentInformation": [
{
"paymentTransactionId": "TestPaymenttransaction",
"paymentMode": "Other",
"paymentDate": "2023-11-15T00:25:56Z"
}
]
}
}
| Body Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
| An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the operation. Type: |
Tutorial: Track a partially fulfilled order
This tutorial walks you through the steps on how to track a partially fulfilled order for items that are low inventory.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. 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 Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. Type: string | No |
address | The destination address for the fulfillment order preview. Type: | Yes |
items | Identifying information and quantity information for the items in the fulfillment order preview. Maximum of 100 line items with a maximum of 250 units per order. | Yes |
shippingSpeedCategories | A list of shipping methods used for creating fulfillment order previews. Possible values:
Note: Shipping method service-level agreements vary by marketplace. Sellers should refer to 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 (cash on delivery (COD). Possible values:
Only applicable for orders in India. Type: Boolean | No |
includeDeliveryWindows | Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The Type: Boolean | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | 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": "LT110WHTAM",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
"quantity": 1
},
{
"sellerSku": "LT205BLKAM",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
"quantity": 1
}
],
"shippingSpeedCategories": [
"Standard"
]
}
Response
A successful response has a 200 code and the response schema for the getFulfillmentPreview operation.
{
"payload": {
"fulfillmentPreviews": [
{
"estimatedFees": [
{
"amount": {
"currencyCode": "USD",
"value": "2"
},
"name": "FBAPerOrderFulfillmentFee"
},
{
"amount": {
"currencyCode": "USD",
"value": "2"
},
"name": "FBATransportationFee"
},
{
"amount": {
"currencyCode": "USD",
"value": "8"
},
"name": "FBAPerUnitFulfillmentFee"
}
],
"estimatedShippingWeight": {
"unit": "POUNDS",
"value": "12.377249768019787"
},
"featureConstraints": [
{
"featureFulfillmentPolicy": "NotRequired",
"featureName": "BLANK_BOX"
},
{
"featureFulfillmentPolicy": "NotRequired",
"featureName": "BLOCK_AMZL"
}
],
"fulfillmentPreviewShipments": [
{
"earliestArrivalDate": "2023-04-15T00:16:14Z",
"earliestShipDate": "2023-04-13T00:16:14Z",
"fulfillmentPreviewItems": [
{
"estimatedShippingWeight": {
"unit": "POUNDS",
"value": "6.394347942660858"
},
"quantity": 1,
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
"sellerSku": "LT110WHTAM",
"shippingWeightCalculationMethod": "PACKAGE"
}
],
"latestArrivalDate": "2023-04-16T00:16:14Z",
"latestShipDate": "2023-04-14T00:16:14Z",
"shippingNotes": []
},
{
"earliestArrivalDate": "2023-04-15T00:16:14Z",
"earliestShipDate": "2023-04-13T00:16:14Z",
"fulfillmentPreviewItems": [
{
"estimatedShippingWeight": {
"unit": "POUNDS",
"value": "7.521162362321674"
},
"quantity": 1,
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
"sellerSku": "LT205BLKAM",
"shippingWeightCalculationMethod": "PACKAGE"
}
],
"latestArrivalDate": "2023-04-16T00:16:14Z",
"latestShipDate": "2023-04-14T00:16:14Z",
"shippingNotes": []
}
],
"isCodCapable": false,
"isFulfillable": true,
"marketplaceId": "ATVPDKIKX0DER",
"scheduledDeliveryinfo": {},
"shippingSpeedCategory": "Standard",
"unfulfillablePreviewItems": []
}
]
}
}
| Name | Description |
|---|---|
fulfillmentPreviews | An array of fulfillment preview information. Type: |
An unsuccessful response has a non-2xx code and includes the following objects. If the PackageNumber does not exist, a 404 response provides the ineligibility errors.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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 Parameter | Description | Required |
|---|---|---|
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
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 | No |
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: | 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: | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The COD charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Items | A list of items to include in the fulfillment order preview, including quantity. Maximum of 100 line items with a maximum of 250 units per order. | 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": "Stockton 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 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Step 3. Validate the order details
Call the getFulfillmentOrder operation to validate fulfillmentAction = Ship and fulfillmentOrderStatus = Received.
| Parameter | Description | Required |
|---|---|---|
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 200 code 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 Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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. To get status change updates, subscribe and listen to FULFILLMENT_ORDER_STATUS notifications.
Step 5. Get the fulfillment order to view the latest order details
After the order is Shipped, the order status notification for Complete is triggered. Now call the getFulfillmentOrder operation to view the latest order details. Call the getFulfillmentOrder operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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 200 code 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": "Stockton Street",
"city": "Alexandria",
"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": "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": [
{
"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-1",
"quantity": "1",
"packageNumber": "1681854637"
}
],
"fulfillmentShipmentPackage": [
{
"packageNumber": "1681854637",
"carrierCode": "Amazon Logistics",
"trackingNumber": "TBA303037991486",
"estimatedArrivalDate": "2022-09-26T03:00:00Z"
}
]
}
],
"returnItems": [],
"returnAuthorizations": []
}
}
| Body Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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.
| Parameter | Description | Required |
|---|---|---|
packageNumber | The unencrypted package identifier returned by the 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 200 code.
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",
"deliveryWindow": {
"earliest": "2019-10-13T20:53:49Z",
"latest": "2019-10-15T12:40:29Z"
},
"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."
}
]
}
}
| Name | Description | Required |
|---|---|---|
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: | No |
estimatedArrivalDate | The estimated arrival date. Type: | No |
shipToAddress | The destination city for the package. Type: | No |
currentStatus | The current delivery status of the package. Type: | No |
currentStatusDescription | Description corresponding to the Type: string | No |
signedForBy | The name of the person who signed for the package. Type: string | No |
additionalLocationInfo | Additional location information. Type: | No |
trackingEvents | An array of tracking event information. Type: | No |
An unsuccessful response has a non-2xx code and includes the following objects. If the PackageNumber does not exist, a 404 response provides the ineligibility errors.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Create an order in hold status and then move it to shipped
This tutorial explains how an order can move from a fulfillment status of HOLD to SHIP. Orders in HOLD status do not proceed to further fulfillment actions until the status is updated to SHIP.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. 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 Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. Type: string | No |
address | The destination address for the fulfillment order preview. Type: | Yes |
items | Identifying information and quantity information for the items in the fulfillment order preview. | Yes |
shippingSpeedCategories | A list of shipping methods used for creating fulfillment order previews. Possible values:
Note: Shipping method service-level agreements vary by marketplace. Sellers should refer to 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 cash on delivery (COD). 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 India.Type: Boolean | No |
includeDeliveryWindows | Specifies whether to return the ScheduledDeliveryInfo response object, which contains the available delivery windows for a Scheduled Delivery. The Type: Boolean | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | 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"
]
}
| Name | Description |
|---|---|
fulfillmentPreviews | An array of fulfillment preview information. Type: |
An unsuccessful response has a non-2xx code and includes the following objects. A 404 response provides the ineligibility errors, if any.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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 don't run on that order.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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: | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The `FulfillmentPolicy` value specified when you submitted the Type: | No |
codSettings | The COD charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Items | A list of items to include in the fulfillment order preview, including quantity. | 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 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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.
| Parameter | Description | Required |
|---|---|---|
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 200 code.
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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. After the order moves to the Ship action, the next fulfillment steps start running on the order.
| Parameter | Description | Required |
|---|---|---|
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 200 code 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 Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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.
After an item is shipped out, the getFulfillmentOrder operation has the serial number in the response for the seller to keep a record of it.
Prerequisites
- The seller needs to share the Regex of the generated serial numbers with Amazon.
- The seller needs to paste the generated unique serial number on every item when inbounding the inventory to Amazon.
- If the customer is using the Amazon Labeling Service, in addition to registering an ASIN, the FNSKU associated with the item must also be registered using the same process.
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Create a fulfillment order with serial numbered items
Call the createFulfillmentOrder operation to create an MCF order with line items that have serial numbers enabled while inbounding to Amazon.
The createFulfillmentOrder request doesn't need any exclusive attributes in the request for this type of order.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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: | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The cash on delivery (COD) charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type:< | No |
| Items | A list of items to include in the fulfillment order preview, including quantity. | 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 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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.
| Parameter | Description | Required |
|---|---|---|
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 200 code 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 Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | Yes |
Step 3. Get the fulfillment order to track status changes
The order goes through status changes, from Planning to Processing to Complete. Subscribe and listen to FULFILLMENT_ORDER_STATUS notifications to be aware of these status changes.
When the order is shipped, the serial number of the item is scanned and validated to match the shared regex.
Call the getFulfillmentOrder operation with the sellerFulfillmentOrderId to view the latest order details and check if the serial number of the item was shipped.
| Parameter | Description | Required |
|---|---|---|
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 200 code 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 Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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 need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Create a Fulfillment order for cross border shipment
Create an order with a US destination address and shipFromCountryCode=CA. In this case, we can skip specifying the marketplaceId in the request and the item is picked from the CA marketplace. Also, include perUnitDeclaredValue in the items of value greater than 0. Call the createFulfillmentOrder operation by passing the following required Body parameters:
| Body Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. | No |
sellerFulfillmentOrderId | A fulfillment order identifier that the seller creates to track their fulfillment order. The 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 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: | 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: | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The cash on delivery (COD) charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Items | A list of items to include in the fulfillment order preview, including quantity. | 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": "Stockton Street",
"city": "Alexandria",
"stateOrRegion": "VA",
"countryCode": "US",
"postalCode": "22308"
},
"items": [
{
"sellerSku": "LT205BLKAM",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
"quantity": 1,
"perUnitDeclaredValue": {
"currencyCode": "USD",
"value": "0.10"
}
}
]
}
Response
A successful response has a 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Create orders with Blank Box and Block AMZL features requested
When creating an order, MCF offers two features which can be specified in the request:
-
Blank Box: Allows the seller to choose boxing with no Amazon logos/labels on it.
-
Block AMZL: Allows the seller to refuse Amazon logistics and rather ship out using another carrier service.
After the request is made during the create order process, it cannot be updated during the fulfillment steps of the order.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. 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 Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. Type: string | No |
address | The destination address for the fulfillment order preview. Type: | Yes |
items | Identifying information and quantity information for the items in the fulfillment order preview. | Yes |
shippingSpeedCategories | A list of shipping methods used for creating fulfillment order previews. Possible values:
Note: Shipping method service-level agreements vary by marketplace. Sellers should refer to 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 cash on delivery (COD). Possible values:
Type: Boolean | No |
includeDeliveryWindows | Specifies whether to return the Type: Boolean | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | 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 200 code 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"
}
]
}
}
| Name | Description |
|---|---|
FulfillmentPreviews | An array of fulfillment preview information. Type: |
An unsuccessful response has a non-2xx code and includes the following objects. A 404 response provides the ineligibility errors, if any.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the getFulfillmentPreview operation. Type: | 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 acts as a default value, but the value specified in the order request takes priority.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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: | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The COD charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type:< | No |
Items | A list of items to include in the fulfillment order preview, including quantity. | 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 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
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.
| Parameter | Description | Required |
|---|---|---|
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 200 code 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 Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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 shows preview details of all ship speeds.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. 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 Parameter | Description | Required |
|---|---|---|
marketplaceId | The marketplace the fulfillment order is placed against. Type: string | No |
address | The destination address for the fulfillment order preview. Type: | Yes |
items | Identifying information and quantity information for the items in the fulfillment order preview. | Yes |
shippingSpeedCategories | A list of shipping methods used for creating fulfillment order previews. Possible values:
Note: Shipping method service-level agreements vary by marketplace. Sellers should refer to 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 cash on delivery (COD). Possible values:
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 Type: Boolean | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | 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 200 code 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": []
}
]
}
}
| Name | Description |
|---|---|
FulfillmentPreviews | An array of fulfillment preview information. Type: |
An unsuccessful response has a non-2xx code and includes the following objects. A 404 response provides the ineligibility errors, if any.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | 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 need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Create 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 when 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 Parameter | Description | Required |
|---|---|---|
EventType | Indicates whether the notification contains order, shipment, or return information. EventType values:
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 Type: string | Yes |
FulfillmentOrderStatus | The current status of the fulfillment order.
Type: string | Yes |
FulfillmentShipment | Delivery and item information for a shipment in a fulfillment order. Type: | No |
FulfillmentReturnItem | Information about an item that was returned to an Amazon fulfillment center. Type: | 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 need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a list of return reason codes for a given product.
Call the listReturnReasonCodes operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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 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 200 code.
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"
}
]
}
}
| Name | Description | Required |
|---|---|---|
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 Type: string | No |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: ErrorList |
Step 2. Create a fulfillment return for an order
Using one of the reasons retrieved in the previous step, make a call to the createFulfillmentReturn operation to submit the return request and retrieve the return shipping label needed to ship the item to Amazon.
Non-prepaid label
This label is not prepaid. It must be paid by the shipper.
| Parameter | Description | Required |
|---|---|---|
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 Type: string | Yes |
| Body Parameter | Description | Required |
|---|---|---|
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 200 code 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"
}
]
}
}
| Name | Description | Required |
|---|---|---|
ReturnItemList | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: < | Yes |
InvalidReturnItemList | An array of invalid return item information. Type: < | Yes |
ReturnAuthorizationList | An array of return authorization information. Type: < | Yes |
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the operation. Type: |
An unsuccessful response has a non-2xx code and includes the following objects. A 404 response provides the ineligibility errors, if any.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | Yes |
Step 3. Ship the returning item
From the previous response, the rmaPageURL provides the return label which needs to be printed and pasted on the package and the postage charges need to be paid by the returning shopper.
Step 4. Get the fulfillment order to validate the order return
After the package is received by the Amazon warehouse, the item is marked returned for that order. Call the getFulfillmentOrder operation to validate that the return authorization is populated on the original order. returnItems and returnAuthorizations should populate the same details as the createFulfillmentReturn response along with the status/condition of the item returned.
| Parameter | Description | Required |
|---|---|---|
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 200 code 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 Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | Yes |
Tutorial: Get dynamic delivery offers
This tutorial outlines how to get dynamic delivery offers for a buyable product using a US ZIP Code or US IP address.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get a dynamic delivery offer
Call the deliveryOffers operation to get the dynamic delivery offer for standard click-to-delivery speed for the specified product and location information.
| Body parameter | Description | Required |
|---|---|---|
product | The product details for the delivery offer. Type: | Yes |
terms | The terms for the delivery offer. Type: | Yes |
Request example
POST "https://sellingpartnerapi-na.amazon.com/fba/outbound/2020-07-01/deliveryOffers"
{
"product": {
"productIdentifier": {
"merchantSku": "TestSku"
},
"amount": {
"unitOfMeasure": "Eaches",
"value": "2"
}
},
"terms": {
"origin": {
"countryCode": "US"
},
"destination": {
"deliveryAddress": {
"countryCode": "US",
"postalCode": "94560",
"addressLine1": "",
"addressLine2": "",
"addressLine3": "",
"city": "",
"districtOrCounty": "",
"stateOrRegion": "CA"
},
"ipAddress": ""
}
}
}
Response
A successful response has a 200 code.
Response example
{
"payload": {
"deliveryOffers": [
{
"dateRange": {
"earliest": "2024-06-07T02:59:00Z",
"latest": "2024-06-07T02:59:00Z"
},
"expiresAt": "2024-06-04T01:32:16Z",
"policy": {
"messaging": {
"locale": "en-US",
"text": "Fastest Delivery Thursday, Jun 6"
}
}
}
]
}
}
If a delivery offer isn't available, deliveryOffers is empty in the response.
{
"payload": {
"deliveryOffers": []
}
}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errored occurred during the Type: |
Tutorial: Create a Japan order with delivery preferences
This tutorial outlines the order creation process for Japan with delivery preferences. This feature is only available for Japan marketplace orders.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Create a fulfillment order specifying the delivery preferences
Call the createFulfillmentOrder operation to create an MCF order specifying the delivery preferences required for the order.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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. ShippingSpeedCategory | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The cash on delivery (COD) charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Items | A list of items to include in the fulfillment order preview, including quantity. | Yes |
Request example
POST "https://sellingpartnerapi-fe.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": "1-8-1 Shimomeguro",
"addressLine2": "Meguro-ku",
"city": "Tokyo",
"countryCode": "JP",
"postalCode": "153-0064"
},
"deliveryPreferences": {
"deliveryInstructions": "Beware of dogs",
"dropOffLocation": {
"type": "FRONT_DOOR"
}
},
"items": [
{
"sellerSku": "SellerSKU12",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
"quantity": 1
}
]
}
Response
A successful response has a 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Create a Japan order providing neighbor details in delivery preferences
This tutorial outlines the order creation process for Japan where the delivery preference is set to a designated neighbor if the recipient is not available at the destination address. This feature is only available for Japan marketplace orders.
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Create a fulfillment order specifying the delivery preferences
Call the createFulfillmentOrder operation to create an MCF order specifying the delivery preferences required for the order.
| Body Parameter | Description | Required |
|---|---|---|
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 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 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: | 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. ShippingSpeedCategory | Yes |
deliveryWindow | The time range within which a Scheduled Delivery fulfillment order should be delivered. Type: | No |
destinationAddress | The destination address for the fulfillment order. Type: | Yes |
deliveryPreferences | The delivery preferences applied to the destination address. These preferences are applied when possible and are best effort. For eligible orders, the default delivery preference is to leave the package unattended at the front door. This feature is currently supported only in the JP marketplace and not applicable for other marketplaces. Type: | No |
fulfillmentAction | Specifies whether the fulfillment order should ship now or have an order hold put on it. Type: | No |
fulfillmentPolicy | The Type: | No |
codSettings | The cash on delivery (COD) charges that you associate with a COD fulfillment order. Type: | 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: | No |
featureConstraints | A list of features and their fulfillment policies to apply to the order. Type: < | No |
Items | A list of items to include in the fulfillment order preview, including quantity. | Yes |
Request example
POST "https://sellingpartnerapi-fe.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": "1-8-1 Shimomeguro",
"addressLine2": "Meguro-ku",
"city": "Tokyo",
"countryCode": "JP",
"postalCode": "153-0064"
},
"deliveryPreferences": {
"deliveryInstructions": "Beware of dogs",
"dropOffLocation": {
"type": "FALLBACK_NEIGHBOR_DELIVERY",
"attributes": {
"neighborName": "Liam Lowe",
"houseNumber": "1-8-2 Shimomeguro"
}
}
},
"items": [
{
"sellerSku": "SellerSKU12",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-0",
"quantity": 1
}
]
}
Response
A successful response has a 200 code and includes the following objects.
Response example
{}
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description |
|---|---|
errors | One or more unexpected errors occurred during the Type: |
Tutorial: Retrieve locker (delivery box) details for packages delivered in Japan
This tutorial shows you how to get locker information for a package that was delivered to a locker (delivery box) for Japan in an outbound shipment for a Multi-Channel Fulfillment order.
The getFulfillmentOrder API might not always return lockerDetails, depending on the delivery status and delivery location.
Use the getPackageTrackingDetails API to check the delivery status and identify if the package was delivered to a locker (delivery box).
Prerequisites
To complete this tutorial, you need:
- Authorization from the selling partner for whom you are making calls. Refer to Authorizing Selling Partner API Applications for more information.
- The Amazon Fulfillment role assigned to your developer profile.
- The Amazon Fulfillment role selected in the App registration page for your application.
Step 1. Get the fulfillment order to view the latest order details and locker details if present
Call the getFulfillmentOrder operation by passing the following parameters:
| Parameter | Description | Required |
|---|---|---|
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 200 code with a payload.
Response example
{
"payload": {
"fulfillmentOrder": {
"sellerFulfillmentOrderId": "CONSUMER-2022921-145045",
"marketplaceId": "ATVPDKIKX0DER",
"displayableOrderId": "CONSUMER-2022921-145045",
"displayableOrderDate": "2024-05-21T14:48:15Z",
"displayableOrderComment": "Thank you for your order",
"shippingSpeedCategory": "Standard",
"destinationAddress": {
"name": "Mary Major",
"addressLine1": "1-8-1 Shimomeguro",
"addressLine2": "Meguro-ku",
"city": "Tokyo",
"countryCode": "JP",
"postalCode": "153-0064"
},
"fulfillmentAction": "Ship",
"fulfillmentPolicy": "FillAllAvailable",
"receivedDate": "2024-05-21T14:50:45Z",
"fulfillmentOrderStatus": "CompletePartialled",
"statusUpdatedDate": "2024-05-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": "2024-05-22T06:59:59Z",
"estimatedArrivalDate": "2024-05-26T06:59:59Z",
"perUnitDeclaredValue": {
"currencyCode": "YEN",
"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": "YEN",
"value": "15.00"
}
}
],
"fulfillmentShipments": [
{
"amazonShipmentId": "T7mfkbDX5",
"fulfillmentCenterId": "TUL2",
"fulfillmentShipmentStatus": "SHIPPED",
"shippingDate": "2024-05-22T03:39:19Z",
"estimatedArrivalDate": "2024-05-26T06:59:59Z",
"fulfillmentShipmentItem": [
{
"sellerSku": "LT205BLKAM",
"sellerFulfillmentOrderItemId": "CONSUMER-2022921-145045-1",
"quantity": "1",
"packageNumber": 1681854637
}
],
"fulfillmentShipmentPackage": [
{
"packageNumber": 1681854637,
"carrierCode": "AMZL",
"trackingNumber": "TBA123456789012",
"estimatedArrivalDate": "2024-05-26T06:59:59Z",
"lockerDetails": {
"lockerNumber": "A-42",
"lockerAccessCode" : "7380"
}
}
]
}
],
"returnItems": [],
"returnAuthorizations": []
}
}
| Body Parameter | Description | Required |
|---|---|---|
fulfillmentOrder | General information about a fulfillment order, including its status. Type: | Yes |
fulfillmentOrderItems | An array of fulfillment order item information. Type: | Yes |
fulfillmentShipments | An array of fulfillment shipment information. Type: | No |
returnItems | An array of items that Amazon accepted for return. Returns empty if no items were accepted for return. Type: | Yes |
returnAuthorizations | An array of return authorization information. Type: | Yes |
An unsuccessful response has a non-2xx code and includes the following objects.
| Name | Description | Required |
|---|---|---|
errors | One or more unexpected errors occurred during the Type: | Yes |
Updated 15 days ago