Amazon Smart Connect - Dispatch Shipments

The purpose of this page is to specify how Hemi will update Shipments to Amazon via the Smart Connect solution to Dispatched

We need to follow the standard Hemi Shipment procedure as per the abstraction.

Ship

Order Shipment Functional Details

When an order is ready to be marked as shipped on the MP we need 2 ids to perform this action. One is the ShipmentID which we already have as part of the Marketplace Order ID. The other is the package ID which we don’t store at the moment and it is going to appear on the order only once the warehouse start packing the order. As we don’t get this information but only get the info that the order is dispatched (which should only be possible if the order is packed) we will need to build a process that will get the Package IDs before sending the actual Dispatch update.

We want to do this whole motion in one flow. This means when all prerequisites in Hemi are met for an order to be picked by the Dispatch Abstraction, the first think we need to do is to make a GetShipment call to Amazon.

See here how to use the getShipment functionality: Amazon Smart Connect - Get Shipment

As we receive the Shipment, from section “packages” (at the end of the payload) we want to take the IDs (can be multiple) to use in the next call for the actual Dispatch update.

Once we’ve obtained the package IDs together with the Shipment ID that we have as part of the Marketplace Order ID in Hemi we can proceed to push a shipping update to the MP as per our standards.

We want to do this in one flow. We don’t care about the actual package IDs, we are not looking to store them, we are not looking to make additional steps for status trackings or anything like this. We just want for the abstraction to pick everything that is ready from Hemi and before pushing it to the actual dispatch call to make a check first with the marketplace for the package IDs as this is info not present in Hemi

Validations - we want to start the shipping process only if it is a full order shipment. We don’t allow partial order shipments in Hemi for Amazon Smart Connect. If any such are present we should mark them as error with the relevant message “Only full Shipments are allowed for Amazon Smart Connect”. Also in a case where the first call (getShipment) fails or doesn’t have Package IDs that we can get we want to store an error for the Shipment in Hemi. If the issue is coming from the call itself we should simply store the error from the message as per the general explanation. If the issue is there are no package IDs we should store “There are no package IDs for this order to proceed with the shipment, please check your Amazon store.”

Note: If my understanding is correct there is the option for multiple package IDs per 1 shipment where we send a call per package ID. In the case where we send multiple calls and any of them fails with an error different than 409 (please see below how to handle this error) we want to just mark the whole shipment as an error in Hemi as we don’t know and we don’t want to track what was in which package at this point in time

This operation is done via the PATCH updatePackageStatus

Example call:

https://sellingpartnerapi-na.amazon.com/externalFulfillment/shipments/2021-01-06/shipments/{shipmentId}/packages/{packageId}?status={status}

Usable Parameters:

I am not 100% sure on this, as it is flagged as Query parameter but it should be just the value we want to update to imo |

Please note - There are some Amazon marketplace channels where Amazon will be performing this action automatically on pickup from the seller warehouse in any such occasions if we are the ones performing this action second (which should be 99% of the case) we will receive a Duplication error and the http status code will be 409. We should treat this as a success as this means that this operation has already worked correctly

Besides this type of error if we’ve received a success for all calls for the order (for each package) before we update it in Hemi we have to follow it up with a final check again with getShipment. This is so we can make a final check that everything is updated as it should be. In the response this time we will be looking for the “Status” field (please see the mapping for getShipments) to be with a “SHIPPED” value (dispatched successfully)

All functions of communication and status updates in Hemi should follow the abstraction rules, and if the dispatch was successful mark Hemi accordingly

If getShipment returns a different status we are to treat the whole operation as a fail and act accordingly with storing the following error in Order Error: “Dispatch operation was not a success based on the additional checks. Please check with Support and/or your Amazon account manager”