Vendor Direct Fulfillment Orders API v2021-23-28 Use Case Guide

The Selling Partner API for Direct Fulfillment Orders provides programmatic access to a direct fulfillment vendor's order data.

API Version: 2021-12-28

What is the Direct Fulfillment Orders API?

Using the Direct Fulfillment Orders API, vendors can receive purchase orders and send order acknowledgements.

The following operations are available:

Operation HTTP Method Path Description
getOrders GET /vendor/directFulfillment/orders/2021-12-28/purchaseOrders Returns a list of purchase orders created during the time frame that you specify. You define the time frame using the createdAfter and createdBefore parameters. You must use both parameters. You can choose to get only the purchase order numbers by setting the includeDetails parameter to false. In that case, the operation returns a list of purchase order numbers. You can then call the getOrder operation to return the details of a specific order.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, see the Tokens API Use Case Guide.

getOrder GET /vendor/directFulfillment/orders/2021-12-28/purchaseOrders /{purchaseOrderNumber} Returns purchase order information for the purchaseOrderNumber that you specify.

Note: This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, see the Tokens API Use Case Guide.

submitAcknowledgement POST /vendor/directFulfillment/orders/2021-12-28/acknowledgements Submits acknowledgements for one or more purchase orders.

You can use the getOrders operation to access orders created during a time frame that you specify (time range of 7 days from a rolling window of the last 6 months, after the vendor went live on the API). You can also get detailed order information for specific orders using the getOrder operation. You can then acknowledge the order using the submitAcknowledgement operation.

📘

Retrieving only order numbers

To retrieve order numbers without complete order details, use the getOrders operation with includeDetails=false as a query parameter. The default value for this parameter is true, so if you don't include this query parameter, you will get the full details of the purchase orders.

The following diagram shows the workflow using the Direct Fulfillment Orders APIs:

Direct Fulfillment orders workflow

The details for each operation are in the sections below.

getOrders

The getOrders operation returns a list of order references (purchase order numbers) or complete order details for all orders which meet the criteria specified. If you only request order numbers, you can use each order number later with the getOrder operation to get order details for a specific order.

📘

Restricted Data Token for authorization

This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, see the Tokens API Use Case Guide.

You should use this API to get purchase orders available to you for fulfillment. Amazon recommends that vendors check for orders at least once per hour during business hours. Depending on your business volume, you may choose to check more frequently. You can return up to 100 orders in one API call. If there are more than 100 orders you can use the nextToken value in the response to get the next set of orders.

The following diagram shows the integration workflow when retrieving purchase orders:

Direct Fulfillment integration workflow when retrieving purchase orders

getOrders Request

To return a list of purchase orders, call the getOrders operation and pass the following parameters:

Query parameters:

+
Name Description Required
shipFromPartyId The vendor warehouse identifier for the fulfillment warehouse. If not specified, the result will contain orders for all warehouses.

Type: string

No
status Returns only the purchase orders that match the specified status. If not specified, the result will contain orders that match any status.

Type: enum ( Status )

No
limitThe limit to the number of purchase orders returned.

Minimum : 1

Maximum : 100

Type: integer (int64)

No
createdAfter Purchase orders that became available after this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
createdBefore Purchase orders that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format.

Type: string (date-time)

Yes
sortOrder Sort the list in ascending or descending order by order creation date.

Type: enum ( SortOrder )

No
nextToken Used for pagination when there are more orders than the specified result size limit. The token value is returned in the previous API call.

Type: string

No
includeDetails When true, returns the complete purchase order details. Otherwise, only purchase order numbers are returned.

Type: string (boolean)

Default: true

No

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/2021-12-28/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true

getOrders Response

A successful response includes the following:

Name Description Required
pagination If more than 100 orders are returned, nextToken is returned in the response for pagination.

Type: string

No
orders Includes details for the purchase order.

Type: < Order > array

No

Response example:

{
  "pagination": {
    "nextToken": "MDAwMDAwMDAwMQ=="
  },
  "orders": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "orderDetails": {
        "customerOrderNumber": "123-ABC",
        "orderDate": "2020-02-20T13:51:00Z",
        "shipmentDetails": {
          "isPriorityShipment": false,
          "isScheduledDeliveryShipment": false,
          "isPslipRequired": true,
          "isGift": false,
          "shipMethod": "UPS_2ND",
          "shipmentDates": {
            "requiredShipDate": "2020-02-21T00:00:00Z",
            "promisedDeliveryDate": "2020-02-24T00:00:00Z"
          },
          "messageToCustomer": "This shipment completes your order. You can always check the status of your orders from the \"Your Account\" link at the top of each page of our site.Thank you for shopping at Amazon.com"
        },
        "taxTotal": {
          "taxLineItem": [
            {
              "taxRate": "0.1",
              "taxAmount": {
                "currencyCode": "USD",
                "amount": "190"
              },
              "type": "TOTAL"
            }
          ]
        },
        "sellingParty": {
          "partyId": "999US"
        },
        "shipFromParty": {
          "partyId": "ABCD"
        },
        "shipToParty": {
          "name": "John Doe",
          "attention": "John Doe",
          "addressLine1": "123 Any Street",
          "addressLine2": "Apt 5",
          "city": "Any Town",
          "stateOrRegion": "CA",
          "postalCode": "94086",
          "countryCode": "USA"
        },
        "billToParty": {
          "partyId": "ABCD"
        },
        "items": [
          {
            "itemSequenceNumber": "00001",
            "buyerProductIdentifier": "B07DFVDRAB",
            "vendorProductIdentifier": "8806098286500",
            "title": "LG 8 kg Inverter Wi-Fi Fully-Automatic Front Loading Washing Machine (FHT1408SWS, STS-VCM, Inbuilt Heater)",
            "orderedQuantity": {
              "amount": 1,
              "unitOfMeasure": "EACH"
            },
            "netPrice": {
              "currencyCode": "USD",
              "amount": "500"
            },
            "taxDetails": {
              "taxLineItem": [
                {
                  "taxRate": "0.1",
                  "taxAmount": {
                    "currencyCode": "USD",
                    "amount": "50"
                  },
                  "type": "TOTAL"
                }
              ]
            },
            "buyerCustomizedInfo": {
              "customizedUrl": "https://1p-df-public-data.s3.amazonaws.com/111-1260745-6291416_58362154013561.zip"
            }
          },
          {
            "itemSequenceNumber": 2,
            "buyerProductIdentifier": "B07DFYF5AB",
            "vendorProductIdentifier": "8806098286123",
            "title": "LG 6.5 kg Inverter Fully-Automatic Front Loading Washing Machine (FHT1065SNW, Blue and White, Inbuilt Heater)",
            "orderedQuantity": {
              "amount": 2,
              "unitOfMeasure": "EACH"
            },
            "netPrice": {
              "currencyCode": "USD",
              "amount": "700"
            },
            "taxDetails": {
              "taxLineItem": [
                {
                  "taxRate": "0.1",
                  "taxAmount": {
                    "currencyCode": "USD",
                    "amount": "140"
                  },
                  "type": "TOTAL"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

getOrder

The getOrder operation returns information about the purchase order that you specify using the purchase order number. The response includes complete purchase order information for the purchase order, including line item details, quantity, cost, etc.

📘

Restricted Data Token for authorization

This is a restricted operation and therefore requires a Restricted Data Token (RDT) for authorization. For more information, see the Tokens API Use Case Guide.

You should use this API to get the details of specific orders returned by the getOrders operation. You can also use this API to get details for any purchase order in the time range of seven days from a rolling window of the last six months after the vendor went live on the API.

The following diagram shows the integration workflow to retrieve a specific purchase order:

Direct Fulfillment integration workflow to retrieve a specific purchase order

Business requirements

Are packing slips required for all orders?

A packing slip is required if it is a Business to Business [B2B] order or a gift order. When isPslipRequired is true, a packing slip is required for the order.

By when should the order be shipped?

You are required to read the value in the requiredShipDate field, which is the latest date the order should be shipped from the warehouse. The promisedDeliveryDate field value denotes the date we promised to deliver to the customer.

Changing an order using the API

Submitting a change to an order using the API is not possible at this time. After an order has been placed, changing it is not possible.

Country specific business requirements

FunctionalityIndiaEuropeNorth America
Net CostConditional. Either net cost or list price.Conditional. Either net cost or list price.Conditional. Either net cost or list price.
List PriceConditional. Either net cost or list price.Conditional. Either Net Cost or List Price.Conditional. Either net cost or list price.
Ship From PartyThe warehouse code assigned to the vendor.The warehouse code assigned to the vendor.The warehouse code assigned to the vendor.
Selling PartyThe vendor code assigned to the vendor.The vendor code assigned to the vendor.The vendor code assigned to the vendor.
Ship To PartyThe address of the customer.The address of the customer.The address of the customer.
Bill To PartyThe address of the bill to entity.The address of the bill to entity.Not applicable.

getOrder Request

To return information about a specific purchase order, call the getOrder operation and pass the following parameter:

Path parameter:

Name Description Required
purchaseOrderNumber The order identifier for the purchase order that you want. Formatting Notes: alpha-numeric code.

Type: string

Yes

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/2021-12-28/purchaseOrders/4Z32PABC

getOrder Response

A successful response includes the following:

Name Description Required
purchaseOrderNumber The purchase order number for this order. Formatting Notes: alpha-numeric code.

Type: string

No
orderDetails Purchase order details.

Type: OrderDetails

No

Response example:

{
  "purchaseOrderNumber": "2JK3S9VC",
  "orderDetails": {
    "customerOrderNumber": "123-ABC",
    "orderDate": "2020-02-20T13:51:00Z",
    "shipmentDetails": {
      "isPriorityShipment": false,
      "isScheduledDeliveryShipment": false,
      "isPslipRequired": true,
      "isGift": false,
      "shipMethod": "UPS_2ND",
      "shipmentDates": {
        "requiredShipDate": "2020-02-21T00:00:00Z",
        "promisedDeliveryDate": "2020-02-24T00:00:00Z"
      },
      "messageToCustomer": "This shipment completes your order. You can always check the status of your orders from the \"Your Account\" link at the top of each page of our site.Thank you for shopping at Amazon.com"
    },
    "taxTotal": {
      "taxLineItem": [
        {
          "taxRate": "0.1",
          "taxAmount": {
            "currencyCode": "USD",
            "amount": "190"
          },
          "type": "TOTAL"
        }
      ]
    },
    "sellingParty": {
      "partyId": "999US"
    },
    "shipFromParty": {
      "partyId": "ABCD"
    },
    "shipToParty": {
      "name": "John Doe",
      "attention": "John Doe",
      "addressLine1": "123 Any Street",
      "addressLine2": "Apt 5",
      "city": "San Jose",
      "stateOrRegion": "Any Town",
      "postalCode": "94086",
      "countryCode": "USA"
    },
    "billToParty": {
      "partyId": "ABCD"
    },
    "items": [
      {
        "itemSequenceNumber": "00001",
        "buyerProductIdentifier": "B07DFVDRAB",
        "vendorProductIdentifier": "8806098286500",
        "title": "LG 8 kg Inverter Wi-Fi Fully-Automatic Front Loading Washing Machine (FHT1408SWS, STS-VCM, Inbuilt Heater)",
        "orderedQuantity": {
          "amount": 1,
          "unitOfMeasure": "EACH"
        },
        "netPrice": {
          "currencyCode": "USD",
          "amount": "500"
        },
        "taxDetails": {
          "taxLineItem": [
            {
              "taxRate": "0.1",
              "taxAmount": {
                "currencyCode": "USD",
                "amount": "50"
              },
              "type": "TOTAL"
            }
          ]
        },
        "buyerCustomizedInfo": {
          "customizedUrl": "https://1p-df-public-data.s3.amazonaws.com/111-1260745-6291416_58362154013561.zip"
        }
      },
      {
        "itemSequenceNumber": "00002",
        "buyerProductIdentifier": "B07DFYF5AB",
        "vendorProductIdentifier": "8806098286123",
        "title": "LG 6.5 kg Inverter Fully-Automatic Front Loading Washing Machine (FHT1065SNW, Blue and White, Inbuilt Heater)",
        "orderedQuantity": {
          "amount": 2,
          "unitOfMeasure": "EACH"
        },
        "netPrice": {
          "currencyCode": "USD",
          "amount": "700"
        },
        "taxDetails": {
          "taxLineItem": [
            {
              "taxRate": "0.1",
              "taxAmount": {
                "currencyCode": "USD",
                "amount": "140"
              },
              "type": "TOTAL"
            }
          ]
        }
      }
    ]
  }
}

submitAcknowledgement

The submitAcknowledgement operation allows vendors to accept or reject a purchase order for fulfillment. Amazon expects a complete acknowledgement, including all purchase order line items of the purchase order. If the vendor does not provide all line items of the purchase order in the acknowledgement, Amazon does not accept the partial acknowledgement.

Amazon expects the vendor to submit the acknowledgement as fast as possible, at the latest within 24 hours. The acknowledgement should be an accurate view of the actual shipment quantities and items.

Verification of successfully submitted order acknowledgements

Vendors can verify the status of the original/updated version of the order acknowledgement using Vendor Central or using the Direct Fulfillment Transaction Management API. Allow the system to take up to 15 minutes to show the original/updated version once submitted. If Vendor Central is not showing the correct values for the acknowledgement, open a Contact Us case in Vendor Central.

The following diagram shows the integration workflow when acknowledging orders.

Direct Fulfillment integration workflow when acknowledging orders

Business Requirements

Can a vendor increase the original quantity submitted in the purchase order using the submitAcknowledgement operation?

No, Amazon does not allow the vendor to send a higher quantity in the acknowledgement than what was submitted in the purchase order.

Is it a requirement to send an order acknowledgement for each purchase order?

Yes, in order to update the status of an order in the Amazon system correctly, Amazon requires PO confirmation using the API or Vendor Central. If you are unable to meet our order acknowledgement requirements using the API, you must confirm your POs using Vendor Central. Please contact your Amazon business representative if you do not have a Vendor Central account.

Is it a requirement to provide every PO line item in the corresponding order acknowledgement?

Yes, so Amazon can update the order status correctly.

How should invalid items or details on an order be reported using the order acknowledgement?

Do not process or ship an item that arrived with an invalid item number on the order. Please return the invalid item number on the acknowledgement and acknowledge it with one of the below codes.

Below is an example of the codes that may be used in the document. Amazon and the vendor will mutually agree upon a list of codes that will be appropriate for their relationship.

Code & Description

  • "00" Shipping 100 percent of ordered product
  • "02" Canceled due to missing/invalid SKU
  • "03" Canceled out of stock
  • "04" Canceled due to duplicate Amazon Ship ID
  • "05" Canceled due to missing/invalid Bill To Location Code
  • "06" Canceled due to missing/invalid Ship From Location Code
  • "07" Canceled due to missing/invalid Customer Ship to Name
  • "08" Canceled due to missing/invalid Customer Ship to Address Line 1
  • "09" Canceled due to missing/invalid Customer Ship to City
  • "10" Canceled due to missing/invalid Customer Ship to State
  • "11" Canceled due to missing/invalid Customer Ship to Postal Code
  • "12" Canceled due to missing/invalid Customer Ship to Country Code
  • "13" Canceled due to missing/invalid Shipping Carrier/Shipping Method
  • "20" Canceled due to missing/invalid Unit Price
  • "21" Canceled due to missing/invalid Ship to Address Line 2
  • "22" Canceled due to missing/invalid Ship to Address Line 3
  • "50" Canceled due to Tax Nexus Issue
  • "51" Canceled due to Restricted SKU/Qty
  • "53" Canceled due to USPS > $400
  • "54" Canceled due to Missing AmazonShipID
  • "55" Canceled due to Missing AmazonOrderID
  • "56" Canceled due to Missing LineItemId
  • "71" Canceled due to discontinued item

📘

Amazon acknowledgement

Amazon expects an acknowledgement even if all the line items on the purchase order were invalid and did not produce an order or invoice.

Do I need to return the same product identifier in the acknowledgement that I received in the orders transaction?

Acknowledgements must return exactly the same product identifier that were sent in the purchase order.

Is it a requirement that I provide an acknowledgement code for all line items regardless of status?

Yes, it is required so we can correctly update the status of the order. If the acknowledgement code is omitted, the acknowledgement will be rejected in our system.

What is the policy at Amazon.com on partial shipments? How should partial shipments be reported when submitting an order acknowledgement?

Partial shipments are not allowed. Vendors need to either confirm or reject the full order (fill or kill model).

Country specific business requirements

There are no country specific requirements for order acknowledgements.

submitAcknowledgement Request

To submit order acknowledgements, call the submitAcknowledgement operation and pass the following parameter:

Body parameter:

Name Description Required
orderAcknowledgements A list of one or more purchase orders.

Type:< OrderAcknowledgementItem > array

Yes

Request example:

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/2021-12-28/acknowledgements
{
  "orderAcknowledgements": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "vendorOrderNumber": "ABC",
      "acknowledgementDate": "2020-02-20T19:17:34.304Z",
      "acknowledgementStatus": {
        "code": "00",
        "description": "Shipping 100 percent of ordered product"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "itemAcknowledgements": [
        {
          "itemSequenceNumber": "00001",
          "buyerProductIdentifier": "B07DFVDRAB",
          "vendorProductIdentifier": "8806098286500",
          "acknowledgedQuantity": {
            "amount": 1,
            "unitOfMeasure": "Each"
          }
        }
      ]
    }
  ]
}

submitAcknowledgements Response

A successful response includes the following:

Name Description Required
transactionId GUID assigned by Amazon to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction.

Type: string

Yes

Response example:

{

  "transactionId": "20190827182357-8725bde9-c61c-49f9-86ac-46efd82d4da5"

}

Acknowledgement use cases

Invalid line item in the purchase order

If the vendor receives an invalid product identifier in the purchase order, the vendor should reject the item with an acknowledgement code "02" and the "description" as "Canceled due to missing/invalid SKU".

{
  "orderacknowledgements": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "vendorOrderNumber": "ABC",
      "acknowledgementDate": "2020-02-20T19:17:34.304Z",
      "acknowledgementStatus": {
        "code": "02",
        "description": "Canceled due to missing/invalid SKU"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "buyerProductIdentifier": "B07DFVDRAB",
          "vendorProductIdentifier": 8806098286500,
          "acknowledgedQuantity": {
            "amount": 1,
            "unitOfMeasure": "Each"
          }
        }
      ]
    }
  ]
}

Out of stock line item in the purchase order

If the vendor receives a product in the purchase order which is now out of stock, the vendor should reject the item with an acknowledgement code "03" and the "description" as "Canceled out of stock".

{
  "orderacknowledgements": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "vendorOrderNumber": "ABC",
      "acknowledgementDate": "2020-02-20T19:17:34.304Z",
      "acknowledgementStatus": {
        "code": "03",
        "description": "Canceled out of stock"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "buyerProductIdentifier": "B07DFVDRAB",
          "vendorProductIdentifier": 8806098286500,
          "acknowledgedQuantity": {
            "amount": 1,
            "unitOfMeasure": "Each"
          }
        }
      ]
    }
  ]
}

Confirm purchase order as accepted

If the vendor receives a product in the purchase order which is available to ship, the vendor should accept the item with an acknowledgement code "00" and the "description" as "Shipping 100 percent of ordered product".

{
  "orderacknowledgements": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "vendorOrderNumber": "ABC",
      "acknowledgementDate": "2020-02-20T19:17:34.304Z",
      "acknowledgementStatus": {
        "code": "00",
        "description": "Shipping 100 percent of ordered product"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "buyerProductIdentifier": "B07DFVDRAB",
          "vendorProductIdentifier": 8806098286500,
          "acknowledgedQuantity": {
            "amount": 1,
            "unitOfMeasure": "Each"
          }
        }
      ]
    }
  ]
}