Amazon Selling Partner API - spapi.cyou

Vendor Direct Fulfillment APIs v1 Use Case Guide

AmazonSPAPI

# Overview

The Selling Partner APIs for Direct Fulfillment help vendors in the direct fulfillment (DF) program manage their direct fulfillment operations programmatically through web service integration. This can help vendors improve and maintain their performance at scale, and grow their business with Amazon.

Vendors can use these APIs to build applications to increase operational efficiency, reduce effort, reduce errors, and improve performance.

For information on authentication and authorization, see the Selling Partner API Developer Guide (opens new window).

# What is the Direct Fulfillment Orders API?

Using the Direct Fulfillment Orders API (opens new window), vendors can receive purchase orders and send order acknowledgements.

The following operations are available:

Operation HTTP Method Path Description
getOrders GET /vendor/directFulfillment/orders/v1/purchaseOrders Get a list of orders based on creation date range.

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/v1/purchaseOrders /{purchaseOrderNumber} Get order details of a specific order by purchase order number.

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/v1/acknowledgements Acknowledge (Accept or Reject) single or multiple orders.

You can use the getOrders (opens new window) 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.

Note: It's possible to get only purchase order numbers without complete order details using the getOrders operation (use "includeDetails=false" in 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.

# Get Purchase Orders

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 return only the order numbers, you can use each order number later with the getOrder operation to get order details for 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 (opens new window).

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 (opens new window) operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId from which the order will be fulfilled. If not specified the result will contain orders for all warehouses.

Type: string

 No
status Returns only orders that belong to this status. If not specified, the result will contain orders in any status.

Type: enum ( Status )

No
limit The limit to the number of records returned.

Type: integer (int64)

 No
createdAfter 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 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 ASC or DESC 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 Default value is true. When true, this API will return a list of orders with complete details. When false or not included in the filter, only purchase order numbers are returned.

Type: string

 No

Request example:

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

# 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

 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": "ABCD",
          "attention": "ABCD",
          "addressLine1": "123 XYZ Street",
          "addressLine2": "Apt 5",
          "city": "San Jose",
          "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"
                }
              ]
            }
          },
          {
            "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"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# Get Purchase Order

The getOrder (opens new window) 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.

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 (opens new window).

You should use this API to get the details of specific orders returned by the getOrders (opens new window) operation. You can also use this API to get details for any purchase order (in the time range of 7 days from a rolling window of last 6 months, after the vendor went live on 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. "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

Functionality India Europe North America
Net Cost Conditional. Either net cost or list price. Conditional. Either net cost or list price. Conditional. Either net cost or list price.
List Price Conditional. Either net cost or list price. Conditional. Either Net Cost or List Price. Conditional. Either net cost or list price.
Ship From Party The warehouse code assigned to the vendor. The warehouse code assigned to the vendor. The warehouse code assigned to the vendor.
Selling Party The vendor code assigned to the vendor. The vendor code assigned to the vendor. The vendor code assigned to the vendor.
Ship To Party The address of the customer. The address of the customer. The address of the customer.
Bill To Party The 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 (opens new window) operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber Order Id for which the details needs to be fetched. Formatting Notes: 8-character alpha-numeric code.

Type: string

 Yes

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders/4Z32PABC
1

# getOrder Response

A successful response includes the following:

Name Description Required
purchaseOrderNumber This field will contain the Amazon Purchase OrderNumber for this order. Formatting Notes: 8-character alpha-numeric code.>

Type: string

 No
orderDetails Details of an order.

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": "ABCD",
      "attention": "ABCD",
      "addressLine1": "123 XYZ Street",
      "addressLine2": "Apt 5",
      "city": "San Jose",
      "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"
            }
          ]
        }
      },
      {
        "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"
            }
          ]
        }
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# Acknowledge Order

The submitAcknowledgement (opens new window) 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 (opens new window) 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

Note: 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 (opens new window) operation and pass the following parameters:

Body parameters:

Name Description Required
orderAcknowledgements Details of individual order being acknowledged.

Type:< OrderAcknowledgementItem > array

Yes

Request example:

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/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"
          }
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# submitAcknowledgements Response

A successful response includes the following:

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

Type: string

 Yes

Response example:

{

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

}
1
2
3
4
5

# 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"
          }
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 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"
          }
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 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"
          }
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# What is the Direct Fulfillment Shipping API?

Vendors can use the Direct Fulfillment Shipping API (opens new window) to exchange shipment related documents with Amazon. Vendors can request shipping labels, receive shipping labels, send shipment confirmations, get packing slips, and retrieve customer invoices.

Please note that customer invoices are specific to the India region.

The following operations are available:

Operation HTTP Method Path Description
submitShippingLabelRequest POST /vendor/directFulfillment/shipping/v1/shippingLabels Submit single or multiple shipping label requests.
getShippingLabels GET /vendor/directFulfillment/shipping/v1/ shippingLabels Get a list of shipping labels based on filter criterion.

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.

getShippingLabel GET

/vendor/directFulfillment/shipping/v1/shippingLabels/{purchaseOrderNumber}

 Get a shipping label by purchase order number.
submitShipmentConfirmations POST /vendor/directFulfillment/shipping/v1/shipmentConfirmations Submit single or multiple shipment confirmations to Amazon.
submitShipmentStatusUpdates POST /vendor/directFulfillment/shipping/v1/shipmentStatusUpdates Submit a shipment status update. Vendor Own Carrier vendors only.
getPackingSlips GET /vendor/directFulfillment/shipping/v1/packingSlips Get a list of packing slips based on creation date range.

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.

getPackingSlip GET /vendor/directFulfillment/shipping/v1/packingSlips/{purchaseOrderNumber} Get the packing slip for a specific order by purchase order number.
getCustomerInvoices GET /vendor/directFulfillment/shipping/v1/customerInvoices Get a list of customer invoices based on filter criterion.

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.

getCustomerInvoice GET /vendor/directFulfillment/shipping/v1/customerInvoices/{purchaseOrderNumber} Get a customer invoice by purchase order number.

# Submit Shipping Label Request

The submitShippingLabelRequest (opens new window) operation allows vendors to request shipping label information from Amazon for each purchase order. You can send multiple shipping label requests in bulk in one API call by adhering to the schema. When shipment labels are created by Amazon, they will be available to download using the getShippingLabel operation.

# Verification of successfully submitted shipping label requests

Vendors can verify the status of their shipping label requests using the Direct Fulfillment Transaction Status API. Allow the system up to 15 min to show the status once submitted. If the transaction status is not updated after 30 minutes, open a "Contact Us" case in Vendor Central.

# Shipping Label Request API integration workflow

The following diagram shows the workflow for submitting shipping label requests.

Direct Fulfillment integration workflow for submitting shipping label requests

# Business Requirements

  • Amazon must receive a shipping label request after the purchase order is confirmed to be accepted by the vendor using the order acknowledgement API.

  • If using Amazon own shipping labels, sending item information or package information in the request is optional.

# Country Specific Business Requirements

No country specific requirements exist.

# submitShippingLabelRequest Request

To request shipping labels, call the submitShippingLabelRequest (opens new window) operation and pass the following parameters:

Body parameters:

Name

Description

 Required
shippingLabelRequests Request one or more shipping labels.

Type: < ShippingLabelRequest > array

Yes

Request example:

POST "https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/shippingLabels"
{
  "shippingLabelRequests": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "containers": [
        {
          "containerType": "carton",
          "containerIdentifier": "123",
          "trackingNumber": "XXXX",
          "dimensions": {
            "length": "12",
            "width": "12",
            "height": "12",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 1,
              "buyerProductIdentifier": "B07DFVDRAB",
              "packedQuantity": {
                "amount": 1,
                "unitOfMeasure": "Each"
              }
            }
          ]
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# submitShippingLabelRequest Response

A successful response includes the following:

Name

Description

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

Type: string

 No

Response example:

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
1
2
3

# Get Shipping Labels

The getShippingLabels (opens new window) operation returns shipping labels for all orders which meet the filter criteria specified in the request. You must have already requested shipping labels using the submitShippingLabelRequest (opens new window) operation before you use this API to get shipping labels available to you for fulfillment. Amazon recommends that vendors check for shipping labels at least once per hour during business hours. Depending on your business volume, you may choose to check more frequently. You can get up to 100 shipping labels in one API call. If there are more than 100 shipping labels you can use the nextToken value to get the next set of shipping labels.

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 (opens new window).

The following diagram shows the integration workflow when retrieving shipping labels:

Direct Fulfillment integration workflow when retrieving shipping labels

# getShippingLabels Request

To retrieve a list of shipping labels, call the getShippingLabels (opens new window) operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId from which the order will be fulfilled. If not specified, the result will contain orders for all warehouses.

Type: string

 No
limit The limit to the number of records returned.

Type: integer

 No
createdAfter Shipping labels 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 Shipping labels 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 ASC or DESC by order creation date.

Type: enum ( SortOrder )

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

Type: string

 No

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/shippingLabels?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC
1

# getShippingLabels Response

A successful response includes the following:

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

Type: string

 No
shippingLabels List of ship labels.

Type: < ShippingLabel > array

No

Response example:

{
  "pagination": {
    "nextToken": "MDAwMDAwMDAwMQ=="
  },
  "shippingLabels": [
    {
      "purchaseOrderNumber": "2JK3S9VC",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "labelFormat": "PNG",
      "labelData": [
        {
          "packageIdentifier": "PKG001",
          "trackingNumber": "1Z6A34Y60369738804",
          "shipMethod": "UPS_GR_RES",
          "shipMethodName": "UPS Ground Residential",
          "content": "Base 64 encoded string goes here "
        }
      ]
    }, {
      "purchaseOrderNumber": "2JK3S9VD",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "labelFormat": "PNG",
      "labelData": [
        {
          "packageIdentifier": "PKG002",
          "trackingNumber": "1Z6A34Y60369738805",
          "shipMethod": "UPS_GR_RES",
          "shipMethodName": "UPS Ground Residential",
          "content": "Base 64 encoded string goes here "
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

# Get Shipping Label

The getShippingLabel (opens new window) operation returns information about the shipping label that you specify using the purchase order number. The response includes complete shipping label information for the purchase order, including label type, purchase order details and ship method.

You can also use this API to get details for any shipping label (in the time range of 7 days from a rolling window of last 6 months, after the vendor went live on API).

The following diagram shows the integration workflow for retrieving a specific shipping label:

Direct Fulfillment integration workflow for retrieving a specific shipping label

# Business Requirements

  • What kind of labels are available to download?

Both ZPL and PNG file format labels are supported. Label content is provided in base64 string format so you can convert the string into desired label format. The choice of label format is with the vendor and they decide this as part of on-boarding process into direct fulfillment program.

  • By when the shipping label should be requested?

ZPL and PNG labels should be requested only on the day when the orders are due for shipping.

# Country Specific Business Requirements

There are no country specific requirements for shipping label responses.

# getShippingLabel Request

To request a shipping label, call the getShippingLabel operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber The purchase order number for which you want to return the shipping label. It should be the same purchaseOrderNumber as received in the order message.

Type: string

 Yes

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/shippingLabels/2JK3S9VC
1

# getShippingLabel Response

A successful response includes the following:

Name Description Required
purchaseOrderNumber This field will contain the Purchase Order Number for this order.

Type: string

 Yes
sellingParty ID of the selling party or vendor.

Type: PartyIdentification

 Yes
shipFromParty Warehouse code of vendor.

Type: PartyIdentification

 Yes
labelFormat Format of the label.

enum ( LabelFormat )

Yes
labelData Provides the details of the packages in this shipment.

Type: < LabelData > array

Yes

Response example:

{
  "purchaseOrderNumber": "2JK3S9VC",
  "sellingParty": {
    "partyId": "999US"
  },
  "shipFromParty": {
    "partyId": "ABCD"
  },
  "labelFormat": "PNG",
  "labelData": [
    {
      "packageIdentifier": "PKG001",
      "trackingNumber": "1Z6A34Y60369738804",
      "shipMethod": "UPS_GR_RES",
      "shipMethodName": "UPS Ground Residential",
      "content": "Base 64 encoded string goes here"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Submit Shipment Confirmations

The submitShipmentConfirmations (opens new window) operation lets vendors submit shipment confirmations to Amazon. Your shipment confirmation allows us to efficiently track your shipments and inform our customers. It contains information about the items being shipped, including purchase order number, ship date, estimated delivery date, and tracking number.

Shipment confirmations allow us to collaborate more effectively with carriers in tracking your shipments.

The lack of valid shipment confirmations can result in:

  • Inadequate visibility about shipments.

  • Errors in reconciling the physical shipments with purchase orders.

  • Manual follow-ups to resolve discrepancies.

# Verification of successfully submitted Shipment Confirmations

Vendors can verify the status of their shipment confirmations via "Vendor Central >Orders> Direct Fulfillment Orders" or using the Direct Fulfillment Transaction Status API. Allow the system up to 10 min to see the status once submitted. If Vendor Central is not showing the correct values for the shipment confirmation, open a "Contact Us" case in Vendor Central. Refer to the Business Requirements section for information about creating shipment confirmations.

The following diagram shows the integration workflow for submitting shipment confirmations:

Direct Fulfillment integration workflow for submitting shipment confirmations

# Business Requirements

  • You should use this API to confirm shipment of an order within 4 hours after the order has shipped from your warehouse.

  • For floor denied shipments, set the "shipmentStatus" field value to "FLOOR_DENIAL".

  • All the purchase order line items should be present in the shipment confirmation. Partial order fulfillment is not allowed. Vendors should reject the order as floor denial if any of the line items are not available to fulfill.

  • The "itemSequenceNumber" for an item should be the same as was received in the order message.

  • Either "buyerProductIdentifier" or "vendorProductIdentifier" is mandatory to send in the shipment confirmation. You need to send the same value as received in the purchase order.

  • For vendor own carriers, sending "scacCode" is mandatory.

  • If the shipment label is provided by Amazon, then the container section is optional since Amazon has access to the package information. Items section is mandatory to submit.

  • The container in a shipment confirmation must have a shipMethod specified.

# Country Specific Business Requirements

None

# submitShipmentConfirmations Request

To submit shipment confirmations, call the submitShipmentConfirmations (opens new window) operation and pass the following parameters:

Body parameters:

Name Description Required
shipmentConfirmations List of confirmed shipments

Type: < ShipmentConfirmation > array

Yes

Request example:

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/shipmentConfirmations
1
{
  "shipmentConfirmations": [
    {
      "purchaseOrderNumber": "PO00050003",
      "shipmentDetails": {
        "shippedDate": "2019-08-07T19:56:45.632Z",
        "shipmentStatus": "SHIPPED",
        "isPriorityShipment": true,
        "estimatedDeliveryDate": "2019-08-07T19:56:45.632Z"
      },
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "partyId": "VENDORWAREHOUSECODE"
      },
      "items": [
        {
          "itemSequenceNumber": 1,
          "buyerProductIdentifier": "ASIN001",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        },
        {
          "itemSequenceNumber": 2,
          "buyerProductIdentifier": "ASIN002",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        },
        {
          "itemSequenceNumber": 3,
          "buyerProductIdentifier": "ASIN003",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        },
        {
          "itemSequenceNumber": 4,
          "buyerProductIdentifier": "ASIN004",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Each"
          }
        }
      ],
      "containers": [
        {
          "containerType": "carton",
          "containerIdentifier": "123",
          "trackingNumber": "TRACK001",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 1,
              "buyerProductIdentifier": "ASIN001",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        },
        {
          "containerType": "carton",
          "containerIdentifier": "234",
          "trackingNumber": "TRACK002",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 2,
              "buyerProductIdentifier": "ASIN002",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        },
        {
          "containerType": "carton",
          "containerIdentifier": "ABCD",
          "trackingNumber": "TRACK003",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 3,
              "buyerProductIdentifier": "ASIN003",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        },
        {
          "containerType": "carton",
          "containerIdentifier": "id12",
          "trackingNumber": "TRACK004",
          "scacCode": "SCAC001",
          "carrier": "ABCD001",
          "shipMethod": "UPS",
          "dimensions": {
            "length": "10",
            "width": "10",
            "height": "10",
            "unitOfMeasure": "IN"
          },
          "weight": {
            "unitOfMeasure": "KG",
            "value": "10"
          },
          "packedItems": [
            {
              "itemSequenceNumber": 4,
              "buyerProductIdentifier": "ASIN004",
              "packedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Each"
              }
            }
          ]
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

# submitShipmentConfirmations Response

A successful response includes the following:

Name Description Required
transactionId GUID 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": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
1
2
3

# Submit Shipment Status Updates

IMPORTANT: Shipment Status Updates are only to be used by VOC (Vendor Own Carrier) vendors. This means vendors that use their own carrier for shipment delivery and do not use Amazon carriers to transport the shipment to the customer. Vendors will ultimately cover the transportation costs and the responsibility to deliver the shipment to customer.

The submitShipmentStatusUpdates (opens new window) operation allows vendors to update the transportation status event for shipments that are on route to the final customer. VOC vendors are required to update shipment status (commonly known as scans) during the transportation phase.

This information will then be forwarded to Amazon customers on the "your Orders" page and thus will improve visibility on the order tracking and delivery process.

Failure to update shipment status updates can result in bad operational KPIs such as low scan rate and eventually warehouse suspension.

# Verification of successfully submitted Shipment Status Updates

Vendors can verify the status of their shipment status updates via "Vendor Central >Orders> Direct Fulfillment Orders" or by using the Direct Fulfillment Transaction Status API. Allow the system up to 10 min to see the status once submitted. If Vendor Central is not showing the correct values for the shipment confirmation, open a "Contact Us" case in Vendor Central. Refer to the Business Requirements section for information about creating shipment confirmations.

The following diagram shows the integration workflow for submitting shipment status updates:

Direct Fulfillment integration workflow for submitting shipment status updates

# Business Requirements

  • You should use this API only if you use your own carrier to transport the shipment to the customer i.e. you are a VOC (Vendor Own Carrier) vendor.

  • You should only use this API to update the status of a shipment after the shipment is confirmed via shipment confirmation API or Vendor Central shipment confirmation.

  • The trackingNumber in the shipment status API should match 100% with the trackingNumber provided in the shipment confirmation, otherwise shipment status update will fail.

  • One Shipment Status Update API call should correspond to one physical package. You can update the shipment status for several packages in one API call by batching them as an array of Shipment Status Updates.

  • A direct fulfillment order can result in several physical packages to be delivered to the customer. Thus, several shipment status updates are needed to reflect the full shipment status of the complete order.

  • Vendors should send shipment status whenever possible following the Amazon Shipment Status guidelines.

  • For scheduled delivery orders, vendors should send the "shipmentSchedule" array that specifies estimated delivery time and delivery window.

# Country Specific Business Requirements

None

# Additional Fields Explanation

1) "statusCode" and "reasonCode"

These fields are standard codes used in EDI standards (for example, ISA X12 and EDIFACT) that are used to provide a specific status event and the reason for the status event. We expect a specific combination of "statusCode" and "reasonCode" that determine an event within the shipment transportation phase to the end customer.

These are the status and reason codes we support and their equivalency to current Vendor Central:

EDIFACT Status Code EDIFACT Reason Code Operational Description Vendor Central UI Equivalency
404 117 Shipment is delayed because of a large scale accident DELAYED
301 000 Shipment delivered to customer DELIVERED
101 000 Shipment has departed the FC DEPARTED_FROM_FC
201 000 Shipment arrived at a carrier facility IN_TRANSIT
409 000 Carrier lost the shipment LOST
302 000 Shipment is out for delivery OUT_FOR_DELIVERY
407 000 Recipient refused to accept the shipment REJECTED
416 000 Shipment is undeliverable and will be destroyed UNDELIVERABLE
X12 Status Code X12 Reason Code Operational Description Vendor Central UI Equivalency
DE AF Shipment is delayed because of a large scale accident DELAYED
D1 NS Shipment delivered to customer DELIVERED
XB NS Shipment has departed the FC DEPARTED_FROM_FC
O1 NS Shipment arrived at a carrier facility IN_TRANSIT
CA PL Carrier lost the shipment LOST
OD NS Shipment is out for delivery OUT_FOR_DELIVERY
A7 AM Recipient refused to accept the shipment REJECTED
AP BG Shipment is undeliverable and will be destroyed UNDELIVERABLE

# submitShipmentStatusUpdates Request

To submit shipment status updates, call the submitShipmentStatusUpdates (opens new window) operation and pass the following parameters:

Body parameters:

Name Description Required
shipmentStatusUpdates List of confirmed shipments.

Type: < ShipmentStatusUpdate > array

Yes

Request example:

POST https://sellingpartnerapi-na.amazon.com/ /vendor/directFulfillment/shipping/v1/shipmentStatusUpdates
{
  "shipmentStatusUpdates": [
    {
      "purchaseOrderNumber": "DX00050015",
      "sellingParty": {
        "partyId": "999US"
      },
      "shipFromParty": {
        "partyId": "ABCD"
      },
      "statusUpdateDetails": {
        "trackingNumber": "TRACK005",
        "statusCode": "D1",
        "reasonCode": "NS",
        "statusDateTime": "2020-08-07T19:56:45Z",
        "statusLocationAddress": {
          "city": "Seattle",
          "postalCode": "98101",
          "stateOrRegion": "Washington",
          "countryCode": "US"
        }
      }
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# submitShipmentStatusUpdates Response

A successful response includes the following:

Name Description Required
transactionId GUID 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": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
1
2
3

# Get Packing Slips

The getPackingSlips (opens new window) operation returns a list of packing slips for the orders which meet the criteria specified. If you need to get a packing slip for a specific order, use the getPackingSlip operation instead.

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 (opens new window).

You should use this API to get packing slips for the 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 get up to 100 packing slips in one API call. If there are more than 100 packing slips, you can use the nextToken value as a parameter in your next request to get the next set.

The following diagram shows the integration workflow when retrieving packing slips:

Direct Fulfillment integration workflow when retrieving packing slips

# getPackingSlips Request

To retrieve packing slips, call the getPackingSlips (opens new window) operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId from which the order will be fulfilled. If not specified the result will contain orders for all warehouses.

Type: string

 No
limit The limit to the number of records returned.

Type: integer

 No
createdAfter Packing slips 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 Packing slips 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 ASC or DESC by packing slip 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

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/packingSlips?createdBefore=2020-06-12T12:00:00-08:00&createdAfter=2020-06-12T00:00:00-08:00&limit=2&sortOrder=DESC
1

# getPackingSlips 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
packingSlips Includes details for the packing slips.

Type: < PackingSlip > array

No

Response example:

{
  "payload": {
    "pagination": {
      "nextToken": "NEBxNEBxNEBxNR=="
    },
    "packingSlips": [
      {
        "purchaseOrderNumber": "UvgABdBjQ",
        "content": "base64 encoded string",
        "contentType": "application/pdf"
      }, {
        "purchaseOrderNumber": "VvgCDdBjR",
        "content": "base64 encoded string",
        "contentType": "application/pdf"
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# Get Packing Slip

The getPackingSlip (opens new window) operation returns information about the specific packing slip that you specify using the purchase order number. The response includes a base64 encoded string of the packing slip. The content type will always be "application/pdf".

The following diagram shows the integration workflow when retrieving a packing slip:

Direct Fulfillment integration workflow when retrieving a packing slip

# Business Requirements

  • Are packing slips required for all orders?

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

# getPackingSlip Request

To return a packing slip, call the getPackingSlip (opens new window) operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber The purchaseOrderNumber for the packing slip you want.

Type: string

 Yes

Request example:

GET https://sellingpartnerapi-na.amazon.com /vendor/directFulfillment/shipping/v1/packingSlips/UkP3YkKDr
1

# getPackingSlip Response

A successful response includes the following:

Name Description Required
purchaseOrderNumber Purchase order number of the shipment.

Type: string

 No
packingSlip

Packing slip information.

Type: PackingSlip

 No

Response example:

{
  "payload": {
    "purchaseOrderNumber": "UvgABdBjQ",
    "content": "base64 encoded string",
    "contentType": "application/pdf"
  }
}
1
2
3
4
5
6
7

# Get Customer Invoices

The getCustomerInvoices (opens new window) operation returns customer invoices for all purchase orders which meet the filter criteria you specify. The use of this API is mandatory only in the India region and not required in any other region. Amazon recommends that vendors check for customer invoices at least once per hour during business hours. Depending on your business volume, you may choose to check more frequently. You can get up to 100 customer invoices in one API call. If there are more than 100 customer invoices you can use the nextToken value as a parameter in the next request to get the next set of customer invoices.

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 (opens new window).

The following diagram shows the integration workflow when retrieving customer invoices:

Direct Fulfillment integration workflow when retrieving customer invoices

# getCustomerInvoices Request

To return customer invoices, call the getCustomerInvoices (opens new window) operation and pass the following parameters:

Query parameters:

Name Description Required
shipFromPartyId The vendor warehouseId from which the order will be fulfilled. If not specified, the result will contain orders for all warehouses.

Type: string

 No
limit The limit to the number of records returned.

Type: integer

 No
createdAfter 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 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 ASC or DESC by order creation date.

Type: enum ( SortOrder )

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

Type: string

 No

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/customerInvoices?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC
1

# getCustomerInvoices Response

A successful response includes the following:

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

Type: string

 No
customerInvoices List of customer invoices.

Type: < CustomerInvoice > array

No

Response example:

{
  "pagination": {
    "nextToken": "MDAwMDAwMDAwMQ=="
  },
  "customerInvoices": [
    {
      "purchaseOrderNumber": "PO98676856",
      "content": "base 64 content goes here"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

# Get Customer Invoice

The getCustomerInvoice (opens new window) operation returns information about the customer invoice that you specify using the purchase order number. The response includes complete customer invoice information for that purchase order.

You can also use this API to get details for any customer invoice (in the time range of 7 days from a rolling window of the last 6 months, after the vendor went live on the API).

The following diagram shows the integration workflow for returning a customer invoice:

Direct Fulfillment integration workflow for retrieving a customer invoice

# Business Requirements

  • What kind of customer invoices are available to download?

The customer invoice is a PDF file which is encoded in binary64 string format. All purchase orders for the India region should have a customer invoice created which should be sent with the shipment.

# Country Specific Business Requirements

Only India region needs to use the customer invoice API.

# getCustomerInvoice Request

To return a customer invoice, call the getCustomerInvoice (opens new window) operation and pass the following parameters:

Path parameters:

Name Description Required
purchaseOrderNumber Purchase order number of the shipment for which to return the invoice.

Type: string

 Yes

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/v1/shippingLabels/2JK3S9VC
1

# getCustomerInvoice Response

A successful response includes the following:

Name Description Required
purchaseOrderNumber The purchase order number for this order.

Type: string

 Yes
content The Base64-encoded customer invoice.

Type: string

 Yes

Response example:

{
  "payload": {
    "purchaseOrderNumber": "PO98676856",
    "content": "base 64 encoded string"
  }
}
1
2
3
4
5
6

# What is the Direct Fulfillment Payments API?

Vendors can use the Direct Fulfillment Payments API to exchange payment related documents with Amazon. The submitInvoice operation allows vendors to send vendor invoices to Amazon for confirmed and shipped orders.

The following operations are included in the Payments API:

Operation HTTP Method Path Description
submitInvoice POST /vendor/directFulfillment/payments/v1/invoices Submits single or multiple vendor invoices to Amazon.

# Submit Invoices

The submitInvoice (opens new window) operation allows vendors to submit vendor invoices to request payment from Amazon for items shipped. Using this API, vendors can submit multiple invoices in a single API call.

Items should be invoiced only after they are confirmed and shipped to Amazon. Otherwise the invoice will be rejected. An invoice with correct information will be processed by Amazon without any human interaction, which means that the vendor receives payment more quickly. Invoices with incorrect information will be rejected in Amazon's payee system, so sending correct information is very important. See the business requirements section to learn how to create invoices with correct information.

# Parallel testing of invoice submission

Vendors need to complete parallel testing with our payments system before they can start using the submitInvoice operation for payment processing. When vendors begin sending their invoices using the API, the parallel testing phase begins. During the parallel testing phase, vendors send both paper and API invoices for all orders shipped. Vendors are required to parallel test until the content of at least 5 to 10 EDI invoice files are validated. Parallel testing is conducted with production POs and invoices. The Amazon API team will contact you when parallel testing is complete, or if there are any content discrepancies in your invoices. When a vendor receives an email saying parallel testing is complete, they no longer need to send paper invoices. From that moment on they can process their payments by sending their invoices using the API.

# Verification of successfully submitted Invoices

The Transaction Status API doesn't show the actual status of invoice processing, it only shows the status of the semantic validations of the submitted invoices. Vendors can verify the actual status of the original/updated version of the invoices via "Vendor Central > Payments > Direct Fulfillment Invoices". For more information on how to use the Transaction Status API, refer to the business use case documentation for Transaction Status. 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 updated invoice, open a "Contact Us" case in Vendor Central.

The following diagram shows the integration workflow for submitting invoices for direct fulfillment confirmed and shipped orders:

Direct Fulfillment integration workflow for submitting invoices for direct fulfillment confirmed and shipped orders

# Business Requirements

  • Invoice numbers must be unique and they should never be reused (even after one year).

  • If an invoice sent using the API has failed due to incorrect data, but a paper invoice has the correct data, then the vendor should update the invoice through the API with the correct data using the same Invoice ID.

  • If an invoice has incorrect data (both paper and API) then the invoice is cancelled and a new invoice should be sent with a new Invoice ID.

  • An invoice with a total amount = 0 should not be sent, as this would cause the invoice to fail.

  • Amazon requires the full address details in the address segments for tax compliance reasons. This is especially important for the bill-to party. For this segment the Amazon Payee system requires an exact match.

  • Payment terms sent in an invoice should match the payment terms agreed upon with the Amazon buyer.

  • Item product identifier should match the order item product identifier that was sent to the vendor in the matching purchase order.

  • The invoice total amount should be equal to the total sum of the items, charges, and allowances.

  • The total of the tax amount for each line level must be equal to the total of the tax amount at the header level.

  • The invoice total quantity should match the sum of the quantity of all items.

  • Every different charge and allowance must be itemized on the header level (for example freight charge, package charge, small ordering charge, etc.).

# Country Specific Business Requirements

Invoices for Direct Fulfillment are not supported in India via the API.

Functionality India Europe North America
Invoice Type Not supported. Invoice type should always be "Invoice". Invoice type should always be "Invoice".
Date Not supported. Must be "now" or before. Must be "now" or before.
HSN Number Not supported. Not used. Not used.
Tax Type at line and header level Not supported. Tax type to be sent. Not Used.
Tax Registration Number Not supported. VAT Number. VAT Number.
Tax Details at line and header level Not supported.

If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item.

The same applies to the total amount of the invoice.

There is also an additional tax type called "DomesticVAT", which can be used to submit the tax amount in the local currency. In order to process the Domestic VAT you must use the same TaxRate used on tax Type "VAT".

If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item.

The same applies to the total amount of the invoice.

Remit To Party Not supported. Tax and address details of the party (vendor) who will be receiving payment for the shipped items. This is required. Tax and address details of the party (vendor) who will be receiving payment for the shipped items. This is required.
Ship From Party Not supported. Vendor code or warehouse code and address of the party from where items will be shipped. Vendor code or warehouse code and address of the party from where items will be shipped.
Ship To Party Not supported. Amazon ID or warehouse code and address of the party to which items will be shipped. Amazon ID or warehouse code and address of the party to which items will be shipped.
Bill To Party Not supported.

Tax and Address details of the party (Amazon) who will be billed for shipped items.

This field is required.

Tax and Address details of the party (Amazon) who will be billed for shipped items.

This field is required.

Amazon Product Identifier and External Product Identifier Not supported. At least one of those values is required. The identifier must be the same as what is received in the order. At least one of those values is required. The identifier must be the same as what is received in the order.
Net Cost Not supported. This field is required. This field is required.
Purchase Order Number Not supported.

One invoice can have information for multiple orders. The PO number should be sent accordingly for different line items.

Required.

One invoice can have information for multiple orders. The PO number should be sent accordingly for different line items.

Required.

Additional Details Not supported. This field is used when the selling party has to submit additional details for special purposes. For example, in the case of Polish split payment invoices, the selling party must send in the detail "mechanizm podzielonej płatności" of type "SUR" and languageCode "PL". Not used
referenceNumber Not supported. Not used. Not used.

# submitInvoice Request

To submit one or more invoices, call the submitInvoice (opens new window) operation and pass the following parameters:

Body parameters:

Name Description Required
invoices The request schema for the submitInvoice operation.

Type: < InvoiceDetail > array

Yes

Request example:

POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/payments/v1/invoices
{
  "invoiceNumber": "0092590411",
  "invoiceDate": "2020-03-13T11:16:24Z",
  "remitToParty": {
    "partyId": "YourVendorCode",
    "address": {
      "name": "vendor name",
      "addressLine1": "vendor address 1",
      "addressLine2": "vendor address 2",
      "addressLine3": "vendor address 3",
      "city": "DECity",
      "county": "Schwabing",
      "district": "München",
      "stateOrRegion": "Bayern",
      "postalCode": "DEPostCode",
      "countryCode": "DE"
    },
    "taxRegistrationDetails": [
      {
        "taxRegistrationType": "VAT",
        "taxRegistrationNumber": "DE123456789"
      }
    ]
  },
  "shipFromParty": {
    "partyId": "ABCD"
  },
  "billToParty": {
    "partyId": "5450534005838",
    "address": {
      "name": "Amazon EU SARL",
      "addressLine1": "Marcel-Breuer-Str. 12",
      "city": "München",
      "county": "Schwabing",
      "district": "München",
      "stateOrRegion": "Bayern",
      "postalCode": "80807",
      "countryCode": "DE"
    },
    "taxRegistrationDetails": [
      {
        "taxRegistrationType": "VAT",
        "taxRegistrationNumber": "DE814584193",
        "taxRegistrationAddress": {
          "name": "Amazon EU SARL",
          "addressLine1": "Marcel-Breuer-Str. 12",
          "city": "München",
          "postalCode": "80807",
          "countryCode": "DE"
        },
        "taxRegistrationMessage": "txmessage"
      }
    ]
  },
  "shipToCountryCode": "DE",
  "paymentTermsCode": "Basic",
  "invoiceTotal": {
    "currencyCode": "EUR",
    "amount": "1428.00"
  },
  "taxTotals": [
    {
      "taxType": "CGST",
      "taxRate": "0.19",
      "taxAmount": {
        "currencyCode": "EUR",
        "amount": "228.00"
      },
      "taxableAmount": {
        "currencyCode": "EUR",
        "amount": "1200.00"
      }
    }
  ],
  "items": [
    {
      "itemSequenceNumber": "1",
      "buyerProductIdentifier": "B00IVLAABC",
      "invoicedQuantity": {
        "amount": 1,
        "unitOfMeasure": "Each"
      },
      "netCost": {
        "currencyCode": "EUR",
        "amount": "1200.00"
      },
      "purchaseOrderNumber": "D3rC3KTxG",
      "vendorOrderNumber": "0092590411",
      "hsnCode": "76.06.92.99.00",
      "taxDetails": [
        {
          "taxType": "CGST",
          "taxRate": "0.19",
          "taxAmount": {
            "currencyCode": "EUR",
            "amount": "228.00"
          },
          "taxableAmount": {
            "currencyCode": "EUR",
            "amount": "1200.00"
          }
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# submitInvoice Response

A successful response includes the following:

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

Type: string

 No

Response example:

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
1
2
3

# What is the Direct Fulfillment Inventory API?

Vendors can use the Direct Fulfillment Inventory API to exchange inventory stock levels with Amazon. We support the Inventory Feeds API, which lets vendors send inventory feeds to Amazon for the direct fulfillment catalog.

The following operations are included:

Operation HTTP Method Path Description
submitInventoryUpdate POST /vendor/directFulfillment/inventory/v1/warehouses/{warehouseId}/items Submits partial or full feeds of inventory details to Amazon.

# Submit Inventory Update

There are two types of inventory feeds that can be submitted using this API. When "isFullUpdate" is set to true, the feed is a full update. When "isFullUpdate" is set to false, the feed is a partial update to inventory. Both options are described below.

When you choose a full update, the operation updates the complete inventory for a specific warehouse. You must send information about all items in the warehouse. For any items not includes, the Available Quantity will be updated to zero. This operation should only be used to perform a full warehouse synchronization, and should only be used if you don't have the ability to update the inventory for out of stock items to zero. If you can manage inventory for all your items, Amazon does not recommend that you choose a full update.

When you choose a partial update, you update only the inventory of selected item(s) in a warehouse. This is typically called every few hours to update the items which are going out of stock or went out of stock since last update.

# Verification of successfully submitted Order inventory feeds

Vendors can verify the status of an inventory update using Vendor Central or using the Transaction Status API. For more information about how to use the Transaction Status API, see the business use case documentation for the Transaction Status 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 for submitting inventory updates.

Direct Fulfillment integration workflow for submitting inventory updates

# Business Requirements

  • One inventory feed is required for each warehouse. If a vendor has multiple warehouses, then multiple inventory feeds submissions are required, with each feed containing items for a given warehouse.

  • For a full update, all the items in the warehouse which are in stock should be submitted. Any items not submitted will have their availability is set to zero in Amazon, and no new orders will be issued for those non-available items.

  • For a partial update, only those items for which the stock quantity must to be updated should be included. Remaining items that are not in the partial update will remain unchanged.

  • When an item's status is set to obsolete using the isObsolete request body parameter, the item is marked as permanently unavailable. If the item becomes available and is back in stock, you must set isObsolete to false so that the item is marked as back in stock.

  • If an item is rejected using the order acknowledgement multiple times, then those items will be marked as 'out of stock' and this may impact your fulfillment metrics.

# Country Specific Business Requirements

No country specific requirements exist.

# submitInventoryUpdate Request

To submit inventory updates, call the submitInventoryUpdate (opens new window) operation and pass the following parameters:

Path parameters:

Name Description Required
warehouseId Identifier for the warehouse for which to update inventory.

Type: string

 Yes

Body parameters:

Name Description Required
inventory Inventory feed request to update all or partial items for a given warehouse.

Type: InventoryUpdate

 Yes

Request example:

POST "https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/inventory/v1/warehouses/ABCD/items"

{
  "inventory": {
    "sellingParty": {
      "partyId": "VENDORID"
    },
    "isFullUpdate": false,
    "items": [
      {
        "buyerProductIdentifier": "ABCD4562",
        "vendorProductIdentifier": "7Q89K11",
        "availableQuantity": {
          "amount": 10,
          "unitOfMeasure": "Each"
        },
        "isObsolete": false
      }, {
        "buyerProductIdentifier": "ABCD4563",
        "vendorProductIdentifier": "7Q89K12",
        "availableQuantity": {
          "amount": 15,
          "unitOfMeasure": "Each"
        },
        "isObsolete": false
      }, {
        "buyerProductIdentifier": "ABCD4564",
        "vendorProductIdentifier": "7Q89K13",
        "availableQuantity": {
          "amount": 20,
          "unitOfMeasure": "Each"
        },
        "isObsolete": false
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# submitInventoryUpdate Response

A successful response includes the following:

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

Type: string

 No

Response example:

{
  "transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
1
2
3

# What is the Direct Fulfillment Transaction Status API?

Vendors can use this API to check the transaction status of their POST transactions.

The following operations are included:

Operation HTTP Method Path Description
getTransactionStatus (opens new window) GET /vendor/directFulfillment/transactions/v1/transactions/{transactionId} Get the status of a POST request.

# Get Transaction Status

Vendors can use the getTransactionStatus (opens new window) operation to check the status of a POST transaction. When a request is posted to Amazon using certain POST operations in the vendor APIs, such as submitAcknowledgement (opens new window) or submitShipmentConfirmations (opens new window), for example, a successful response contains a transaction ID that uniquely identifies the transaction. Amazon will process the transaction asynchronously, and the final response will be available via the getTransactionStatus operation.

See the corresponding integration workflow diagram in the other sections of this guide to understand when to call the getTransactionStatus operation to get the transaction status.

Amazon offers the final processed status for POST transactions such as submitAcknowledgement and submitShipmentConfirmations via this API. We highly recommend that vendors check the status using this API to ensure that transactions were processed successfully. If an error occurred you will receive the error details so you can correct the transaction and resubmit it.

Transaction Status Definition
Processing The API transaction was received by Amazon is being processed. The processing is not completed yet. Check the SLA for each API operation for the expected time to complete processing.
Success The API transaction was successfully processed by Amazon.
Failure The API transaction failed during processing. The error details will be provided in the getTransactionStatus response body.

NOTE:

The transaction status is supported for the following Direct Fulfillment APIs:

Description API Section Operation
Acknowledge Order Direct Fulfillment Orders submitAcknowledgement
Submit Shipment Confirmations Direct Fulfillment Shipping submitShipmentConfirmations
Shipping Label Request Direct Fulfillment Shipping submitShippingLabelRequest
Shipping Status Updates Direct Fulfillment Shipping submitShipmentStatusUpdates
Inventory Update Direct Fulfillment Inventory submitInventoryUpdate
Invoice Direct Fulfillment Payments submitInvoice

The transaction status supports only "Processing" and "Failure" status codes for now. If the transaction status is "Processing" and has not been updated to "Failure" after 30 minutes, that indicates the transaction has successfully processed in our systems. The "Success" status will be supported in the future.

# getTransactionStatus Request

To return the transaction status, call the getTransactionStatus (opens new window) operation and pass the following parameters:

Path parameters:

Name Description Required
transactionId Previously returned in the response to the POST request of a specific transaction.

Type: string

 Yes

Request Example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/transactions/v1/transactions/20190904190535-eef8cad8-418e-4ed3-ac72-789e2ee6214a
1

# getTransactionStatus Response

A successful response includes the following:

Name Description Required
transactionId The unique identifier returned in the response to the post request of a specific transaction.

Type: string

 Yes
status Current processing status of the transaction.

enum ( Status )

Yes
errors Error code and message for the failed transaction. Only available when transaction status is 'Failure'.

Type: ErrorList

 No

Response Example:

{
  "transactionId": "20190918190535-eef8cad8-418e-456f-ac72-789e2ee6813c",
  "status": "Failure",
  "errors": [
    {
      "code": "INVALID_ORDER_ID",
      "message": "Invalid order ID."
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11

Vendor Retail Procurement APIs v1