Submit shipment status updates

Learn how to use the Vendor Direct Fulfillment Shipping API to submit shipment status updates. 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.

🚧

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.

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 the trackingNumber 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:

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• The Direct-to-Consumer Shipping (Restricted) role assigned to your developer profile.
• The Direct-to-Consumer Shipping (Restricted) role selected in the app registration page for your application.

Submit shipment status updates

To submit shipment status updates, call the submitShipmentStatusUpdates operation.