Vendor Direct Fulfillment Orders API v1 Use Case Guide

Use the Direct Fulfillment Orders API to receive purchase orders and send order acknowledgements.

The following operations are available:

You can use the getOrders operation to access orders created during a time frame that you specify (time range of seven days during the past six 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 customer data transmission

Vendors do not receive customer data such as name, address, or phone number for certain orders available through the getOrder and getOrders operations. Direct Fulfillment shares customer information directly on Amazon provided shipping labels. This applies to all shipments fulfilled by Amazon label only vendors and Amazon Transportation Services.

Customer name, address, and phone number are available if your operations require you to generate a label using a Direct Fulfillment Amazon carrier account. The information is also available to you if you use a vendor own label (VOL) or vendor own carrier (VOC) shipping label to fulfill the Direct Fulfillment order. If you generate your own AMXL shipping labels, you can access customer data.

⭐

Tip

If you use AMXL and AT shipping methods for the same warehouse, the AMXL Oversize and XL markers on the label help differentiate between AMXL and AT labels.

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, refer to 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 can 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:

getOrders Request

To return a list of purchase orders, call the getOrders operation.

Query parameters:

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, and cost.

📘

Restricted Data Token for authorization

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

You should use this API to get the details of specific orders returned by the getOrders operation.

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

Country specific business requirements

⭐

Tip

To learn how to check that your vendor group contains all of the vendor codes that you want your application to access, and add new vendor codes to your account, refer to Authorize your Application to Access Vendor Groups.

getOrder Request

To return information about a specific purchase order, call the getOrder operation.

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 after submission. 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.

Business Requirements

The following list is an example of the codes that can be used in the Amazon acknowledgement. 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.

submitAcknowledgement Request

To submit order acknowledgements, call the submitAcknowledgement operation.

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"
          }
        }
      ]
    }
  ]
}