Vendor Direct Fulfillment Shipping API v2021-12-28 Use Case Guide
Learn how to use the Vendor Direct Fulfillment (DF) Shipping API.
Use the Direct Fulfillment Shipping API to exchange shipment-related documents with Amazon.
Tutorials
The tutorials in this section describe how to:
- Submit shipping label requests
- Get one or more shipping labels
- Create shipping labels and container labels
- Submit shipment confirmations and shipment status updates
- Get one or more packing slips
- Get one or more customer invoices (India only)
Submit shipping label requests
The submitShippingLabelRequest
operation lets vendors 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.
Note
The
submitShippingLabelRequest
operation is only available to vendors who use Amazon carriers.
Verify shipping label submission requests
You can verify the status of your shipping label requests using the Vendor DF Transactions API. Allow the system up to 15 minutes to show the status after submission. If the transaction status is not updated after 30 minutes, open a Contact Us case in Vendor Central.
The following diagram shows the workflow for submitting shipping label requests.
Business requirements
-
The purchase order must be successfully confirmed via API, EDI, or Vendor Central before you submit the shipping label request. Shipping label requests for unconfirmed or cancelled purchase orders are rejected.
-
If you use Amazon-owned shipping labels, sending item information or package information in the request is optional.
submitShippingLabelRequest
request
submitShippingLabelRequest
requestTo request shipping labels, call the submitShippingLabelRequest
operation and pass the following body parameter:
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/2021-12-28/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"
}
}
]
}
]
}
]
}
submitShippingLabelRequest
response
submitShippingLabelRequest
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
transactionId | GUID to identify this transaction. This value can be used with the Vendor DF Transactions API to return the status of this transaction.<br.>Type: string | No |
Response example
{
"transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
Get shipping labels
The getShippingLabels
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
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 can 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.
Shipping labels expire 90 days after their creation date (the submitShippingLabelRequest
date).
Note
This is a restricted operation and requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.
The following diagram shows the integration workflow when retrieving shipping labels:
getShippingLabels
request
getShippingLabels
requestTo retrieve a list of shipping labels, call the getShippingLabels
operation and pass the following query parameters:
Name | Description | Required |
---|---|---|
shipFromPartyId | The vendor warehouseId for order fulfillment. If not specified, the response 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 response. 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 ascending (ASC ) or descending (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/2021-12-28/shippingLabels?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC
getShippingLabels
response
getShippingLabels
responseA 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 "
}
]
}
]
}
Get a shipping label
The getShippingLabel
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.
Shipping labels expire 90 days after their creation date (the submitShippingLabelRequest
date).
Note
This is a restricted operation and requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.
You can also use this API to get details for any shipping label (in the time range of seven days from a rolling window of last six months, after the vendor went live on API).
The following diagram shows the integration workflow for retrieving a specific shipping label:
Business requirements
- What kind of labels are available to download?
The supported label formats are ZPL and PNG. Label content is provided in Base 64 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 must I request the shipping label?
Only request your shipping labels on the day that the orders are shipped.
getShippingLabel
request
getShippingLabel
requestTo request a shipping label, call the getShippingLabel
operation and pass the following path parameter:
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.Type: string | Yes |
Request example
GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shippingLabels/2JK3S9VC
getShippingLabel
response
getShippingLabel
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
purchaseOrderNumber | The purchase order number for this order. Type: string | Yes |
sellingParty | The identifier of the selling party or vendor. Type: PartyIdentification | Yes |
shipFromParty | The warehouse code of the vendor. Type: PartyIdentification | Yes |
labelFormat | The 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"
}
]
}
Create shipping labels
The createShippingLabels
operation creates shipping labels for a purchase order and returns the labels. This is a synchronous operation and does not require calling the Vendor DF Transactions API.
Note
This is a restricted operation and requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.
The following diagram shows the workflow for creating shipping labels using the createShippingLabels
operation.
Business requirements
You can return shipping labels for one purchase order per request. Multiple purchase orders in a single request is not supported.
createShippingLabels
request
createShippingLabels
requestTo create shipping labels synchronously, call the createShippingLabels
operation and pass the following path parameter:
Name | Description | Required |
---|---|---|
purchaseOrderNumber | The purchase order number for the shipping labels you want. Type: string | Yes |
You can include the following body parameters:
Name | Description | Required |
---|---|---|
sellingParty | The ID of the selling party or vendor. Type: PartyIdentification | Yes |
shipFromParty | Warehouse code of vendor. Type: PartyIdentification | Yes |
containers | A list of the packages in this shipment. Type: < Container > array | No |
Request example
POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/
shipping/2021-12-28/shippingLabels/XhvBghry
{
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
}
}
createShippingLabels
response
createShippingLabels
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
purchaseOrderNumber | The purchase order number for this order. Type: string | Yes |
sellingParty | The identifier of the selling party or vendor. Type: PartyIdentification | Yes |
shipFromParty | The warehouse code of the vendor. Type: PartyIdentification | Yes |
labelFormat | The format of the label. enum ( LabelFormat ) | Yes |
labelData | Provides the details of the packages in this shipment. Type: < LabelData > array | Yes |
Response example
{
"purchaseOrderNumber": "XhvBghry",
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"labelFormat": "PNG",
"labelData": [
{
"packageIdentifier": "1",
"trackingNumber": "1Z69664F0310685739",
"shipMethod": "UPS_GR_RES_SIG",
"shipMethodName": "UPS Ground Residential",
"content": "Base 64 encoded string goes here"
}
]
}
Response example (error)
{
"errors": [
{
"code": "InvalidInput",
"message": "[MISMATCHED_ITEM]: Request Rejected: Order quantity does not match the shipped quantity. All items in the order must be provided. Ensure you add the correct quantity of shipped items to packages. For items - ${fnSku}, the expected quantity is ${expectedQuantity}, but the provided quantity is ${providedQuantity}.",
"details": ""
}
]
}
List of possible error response details
The following table contains a list of all possible error response details. Included are any recommended steps to take to resolve the error condition before retrying the request. You should design a failure handling mechanism in your application to anticipate and handle these potential errors.
It is possible that additional error responses will be added over time, so your application should also be prepared to gracefully handle errors that are not included in this list.
Bracketed values preceded by a \$
that appear in the Message column (for example, \${fnSku}
) are replaced with actual values in the error response.
Code | Message | Details |
---|---|---|
InvalidInput | [MISMATCHED_ITEM]: Request Rejected: Order quantity does not match the shipped quantity. All items in the order must be provided. Ensure you add the correct quantity of shipped items to packages. For items - ${fnSku}, the expected quantity is ${expectedQuantity}, but the provided quantity is ${providedQuantity}. | None |
InvalidInput | [NO_ITEMS_PRESENT]: Request Rejected: Order ID ${shipmentId} has items not assigned to any package(s). Please make sure all items are map to the package(s). | None |
InvalidInput | [PACKAGE_DIMENSION_NOT_VALID]: Request Rejected: Order ID ${shipmentId} has invalid dimension for the package(s). Please add valid dimensions for your package(s). | None |
InvalidInput | [PACKAGE_WEIGHT_NOT_VALID]: Request Rejected: Order ID ${shipmentId} has invalid weight for the package(s). Please add valid weight for your package(s). | None |
InvalidInput | [PIECE_NUMBER_ONE_NOT_PROVIDED]: The container sequence number '1' is not provided for at least one item. Check if the container sequence number is missing | None |
InvalidInput | [INCONSISTENT_PIECE_NUMBER_QUANTITY]: The container sequence number of at least one item is either not consistent or incompatible with the item quantity. Verify the container sequence number is correct, and the quantity of each item is the same as the item sequence number | None |
InvalidInput | [INVALID_VENDOR_CODE]: Invalid vendor code ${vendorCode}. Verify that the vendor code is correct for the order | None |
InvalidInput | [INVALID_ORDER_ID_WAREHOUSE_COMBINATION]: Shipping Label Rejected: Order ID ${shipmentId} doesn't belong to warehouse ${warehouseCode}. Please verify that the warehouse code and Order Id are correct | None |
InvalidInput | [INCORRECT_VENDOR_GROUP_ID]: Invalid vendor group Id ${vendorGroupId}. Verify that the vendor group Id is correct for the order | None |
InvalidInput | [DUPLICATE_VENDOR_PACKAGE_ID]: Duplicate VendorPackageIds. Please fix the Duplicate container identifiers and try again | None |
InvalidInput | [EMPTY_VENDOR_PACKAGE_ID]: Invalid VendorPackageIds. Please fix the Invalid container identifiers and try again | None |
InvalidInput | [SHIP_METHOD_NOT_SUPPORTED]: ${ship_method} is not supported. Use your existing set-up to generate the label for ${ship_method} | None |
InvalidInput | [SHIP_METHOD_CHANGED]: The ship method for this PO has changed from ${old_ship_method} to ${ship_method}. Use your existing set-up to generate the label for ${ship_method} | None |
InvalidInput | [INCONSISTENT_SHIP_METHODS]: Request Rejected: Different ship methods are assigned across different packages. Try to ship all items in a single box. If that is not possible, please contact us. | None |
ConflictError | [SHIPMENT_NOT_MUTABLE]: Request Rejected: Package dimensions for Order ID ${shipmentId} cannot be updated with current status. No further action is required. | None |
ConflictError | [ORDER_SHIPPED_WITH_VENDOR_LABEL]: You have already shipped the order with a carrier other than Amazon Transportation, therefore you can't print the label for this order. No action is required. You have already confirmed the shipped order. | None |
InternalFailure | We encountered an internal error. Please try again. | None |
Submit shipment confirmations
The submitShipmentConfirmations
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 Vendor DF Transactions API. Allow the system up to 10 min to determine the status after submission. 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:
Business requirements
-
Use this API to confirm shipment of an order within four hours after the order has shipped from your warehouse.
-
For floor denied shipments, set the
shipmentStatus
field value toFLOOR_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
orvendorProductIdentifier
is mandatory to send in the shipment confirmation. You need to send the same value as received in the purchase order. -
For VOcs, 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.
submitShipmentConfirmations
request
submitShipmentConfirmations
requestTo submit shipment confirmations, call the submitShipmentConfirmations
operation and pass the following body parameter:
Name | Description | Required |
---|---|---|
shipmentConfirmations | List of confirmed shipments. Type: < ShipmentConfirmation > array | Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/shipmentConfirmations
{
"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"
}
}
]
}
]
}
]
}
submitShipmentConfirmations
response
submitShipmentConfirmations
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
transactionId | GUID to identify this transaction. This value can be used with the Vendor DF Transactions API to return the status of this transaction. Type: string | Yes |
Response example
{
"transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
Submit shipment status updates
Caution
Only Vendor Own Carrier (VOC) vendors can use Shipment Status Updates. This means vendors that use their own carrier for shipment delivery, rather than Amazon carriers, to transport shipments to customers. VOC vendors ultimately cover the transportation costs and the responsibility to deliver shipments to customers.
The submitShipmentStatusUpdates
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 in Vendor Central > Orders > Direct Fulfillment Orders or by using the Vendor DF Transactions API. Allow the system up to 10 minutes to determine the status after submission. 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:
Business requirements
-
Only use this API if you use your own carrier (you are a VOC vendor) to transport the shipment to the customer.
-
Use this API to update the status of a shipment after the shipment is confirmed (through API or Vendor Central).
-
The
trackingNumber
in the shipment status API must match thetrackingNumber
provided in the shipment confirmation. If it doesn't match, the shipment status update fails. -
One
submitShipmentStatusUpdates
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 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.
Additional fields
statusCode
and reasonCode
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
submitShipmentStatusUpdates
requestTo submit shipment status updates, call the submitShipmentStatusUpdates
operation and pass the following body parameter:
Name | Description | Required |
---|---|---|
shipmentStatusUpdates | List of confirmed shipments. Type: < ShipmentStatusUpdate > array | Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/ /vendor/directFulfillment/shipping/2021-12-28/shipmentStatusUpdates
{
"shipmentStatusUpdates": [
{
"purchaseOrderNumber": "DX00050015",
"sellingParty":
{
"partyId": "999US"
},
"shipFromParty":
{
"partyId": "ABCD"
},
"statusUpdateDetails":
{
"trackingNumber": "TRACK005",
"statusDateTime": "2020-08-07T19:56:45Z",
"statusCode": "D1",
"reasonCode": "NS",
"statusLocationAddress":
{
"name": "ABC",
"addressLine1": "1st street",
"city": "Seattle",
"countryCode": "US",
"postalCode": "124",
"stateOrRegion": "CA"
}
}
}
]
}
submitShipmentStatusUpdates
response
submitShipmentStatusUpdates
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
transactionId | GUID to identify this transaction. This value can be used with the Vendor DF Transactions API to return the status of this transaction. Type: string | Yes |
Response example
{
"transactionId": "20190905010908-8a3b6901-ef20-412f-9270-21c021796605"
}
Get packing slips
The getPackingSlips
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 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 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 can 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 of packing slips.
The following diagram shows the integration workflow when retrieving packing slips:
getPackingSlips
request
getPackingSlips
requestTo retrieve packing slips, call the getPackingSlips
operation and pass the following 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 ascending (ASC ) or descending (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/2021-12-28/packingSlips?createdBefore=2020-06-12T12:00:00-08:00&createdAfter=2020-06-12T00:00:00-08:00&limit=2&sortOrder=DESC
getPackingSlips
response
getPackingSlips
responseA 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
{
"pagination": {
"nextToken": "NEBxNEBxNEBxNR=="
},
"packingSlips": [
{
"purchaseOrderNumber": "UvgABdBjQ",
"content": "base64 encoded string",
"contentType": "application/pdf"
},
{
"purchaseOrderNumber": "VvgCDdBjR",
"content": "base64 encoded string",
"contentType": "application/pdf"
}
]
}
Get a packing slip
The getPackingSlip
operation returns the packing slip for the purchase order number that you specify. The response includes a base64 encoded string of the packing slip. The content type will always be "application/pdf".
Note
This is a restricted operation and requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.
The following diagram shows the 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
getPackingSlip
requestTo return a packing slip, call the getPackingSlip
operation and pass the following path parameter:
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/2021-12-28/packingSlips/UkP3YkKDr
getPackingSlip
response
getPackingSlip
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
purchaseOrderNumber | Purchase order number of the shipment. Type: string | Yes |
content | A Base64encoded string of the packing slip PDF. Type: string | Yes |
contentType | The format of the file (such as PDF, JPEG). Type: enum ( ContentType ) | No |
Response example
{
"purchaseOrderNumber": "UvgABdBjQ",
"content": "base64 encoded string",
"contentType": "application/pdf"
}
Get customer invoices (India only)
The getCustomerInvoices
operation returns customer invoices for all purchase orders which meet the filter criteria you specify.
Important
The
getCustomerInvoices
operation is mandatory in the India marketplace. It is not available to any other marketplace.
Amazon encourages vendors to check for customer invoices at least once per hour during business hours. Depending on your business volume, you can 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 requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.
The following diagram shows the integration workflow when retrieving customer invoices:
getCustomerInvoices
request
getCustomerInvoices
requestTo return customer invoices, call the getCustomerInvoices
operation and pass the following 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 ascending (ASC ) or descending (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/2021-12-28/customerInvoices?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC
getCustomerInvoices
response
getCustomerInvoices
responseA 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: Pagination | No |
customerInvoices | List of customer invoices. Type: < CustomerInvoice > array | No |
Response example
{
"pagination": {
"nextToken": "MDAwMDAwMDAwMQ=="
},
"customerInvoices": [
{
"purchaseOrderNumber": "PO98676856",
"content": "base 64 content goes here"
}
]
}
Get a customer invoice (India only)
The getCustomerInvoice
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.
Note
This is a restricted operation and requires a Restricted Data Token (RDT) for authorization. For more information, refer to the Tokens API Use Case Guide.
You can also use this API to get details for any customer invoice (in the time range of seven days from a rolling window of the last six months, after the vendor went live on the API).
The following diagram shows the integration workflow for returning 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.
getCustomerInvoice
request
getCustomerInvoice
requestTo return a customer invoice, call the getCustomerInvoice
operation and pass the following path parameter:
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/2021-12-28/shippingLabels/2JK3S9VC
getCustomerInvoice
response
getCustomerInvoice
responseA 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
{
"purchaseOrderNumber": "PO98676856",
"content": "base 64 encoded string"
}
Create a container label
Use the createContainerLabel
operation to request and receive a pallet label from Amazon for each palletized load. The response includes a 4X6 printable pallet label that contains the label type and pallet ID.
Business requirements
The createContainerLabel
operation does not support multiple pallet label requests in one API call. If you want to retrieve pallet labels for multiple pallets, you must send multiple createContainerLabel
requests in parallel.
createContainerLabel
request
createContainerLabel
requestTo create a container label, call the createContainerLabel
operation and pass the following body parameters:
Name | Description | Required |
---|---|---|
sellingParty | The ID of the selling party or vendor. Type: PartyIdentification | Yes |
shipFromParty | The warehouse code of the vendor. Type: PartyIdentification | Yes |
vendorContainerId | The vendor's unique identifier for the container. Type: VendorContainerId | Yes |
carrierId | The container (pallet) label's carrier. Type: CarrierId | Yes |
packages | An array of package objects that associates shipment packages with a container. Type: Packages | Yes |
Request example
POST https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/shipping/2021-12-28/containerLabel
{
"sellingParty": {
"partyId": "999US"
},
"shipFromParty": {
"partyId": "ABCD"
},
"vendorContainerId": "000011189212211212",
"carrierId": "SWA",
"packages": [
{
"packageTrackingNumber": "TBA134335066000"
},
{
"packageTrackingNumber": "TBA214335089000"
},
{
"packageTrackingNumber": "TBA311235066000"
}
]
}
createContainerLabel
response
createContainerLabel
responseA successful response includes the following:
Name | Description | Required |
---|---|---|
containerTrackingNumber | The container (pallet) tracking identifier from the shipping carrier. Type: string | Yes |
content | The container label content encoded into a Base64 string. Type: string | Yes |
format | The format of the container label. Type: ContainerLabelFormat | Yes |
Response example
{
"containerLabel": {
"containerTrackingNumber": "TBA134335066000",
"content": "Base64 encoded string",
"format": "PNG"
}
}
Updated 4 days ago