Amazon Smart Connect - Get Shipments

New Status for downloading orders | | 1.5 | Milen Markov | 26.11.2024 | Logic to skip the minus sign when saving discounts and summing up product discounts into order total discount |

The purpose of this doc is to explain the specifications of downloading and storing the Amazon Shipments for the Smart Connect model.

As described in the master doc we treat each shipment as a separate order. Each communication back to Amazon will be based on the unique Shipment ID. For this purpose we are to use the Shipment ID as a part of the Marketplace Order ID reference. To keep our standard flow though and to be able to identify shipments that no longer “exist” by the Amazon Order ID we will concatenate the OrderID + ShipmentID in our Marketplace Order ID reference to achieve uniqueness and communication streamline in the following format OrderId_ShipmentId

This operation is done via the GET getShipments

Example call:

https://sellingpartnerapi-na.amazon.com/externalFulfillment/shipments/2021-01-06/shipments?locationId=&status=&lastUpdatedAfter=&lastUpdatedBefore=&maxResults=&nextToken=

Usable parameters:

fetch all new shipments which would be in the ACCEPTED status. Valid values are ACCEPTED, UNFULFILLABLE, CONFIRMED, PACKAGE_CREATED, PICKUP_SLOT_RETRIEVED, INVOICE_GENERATED, SHIPLABEL_GENERATED, SHIPPED, DELIVERED and CANCELLED | String | Yes | There is no way to just call for “all” orders, we have to check them by status. The most important status for the create new orders to kick off the process is the “ACCEPTED” status. For detailed description on the statuses please see table “Amazon Shipment Statuses” below. For business requirements on the statuses please see “More Statuses Information” right after the table | | lastUpdatedAfter | Shipments whose latest update is after the specified date/time are included in the response. This field should be in the ISO8601 date/time format | Date | No | We are to use this field to filter out based on our standard “Last Run” functionality. 15 minutes overlap to be used for d2d use. 5 days back to be used on our first run | | lastUpdatedBefore | Shipments whose latest update is before the specified date/time are included in the response. This field should be in the ISO8601 date/time format | Date | No | N/A | | maxResults | Specify the number of shipments to be included in the response | Integer | No | N/A | | nextToken | The nextToken value returned from a previous call to get shipments. Use this to retrieve the next page of shipments | String | No | Just to note that we need to be using the token as present so we don’t miss multiple pages in responses |

Amazon Shipment Statuses:

manually status update by invoking update-package-status API or via logistics scan events#). This is a terminal status in the shipment processing workflow | Shipped | Indicates the order is in transit | | DELIVERED | This status indicates that the shipment is delivered to the customer. Note. Currently it is only available for Amazon IN SellerFlex channel | Shipped | Indicates the order has been delivered to the end customer. Available only in a few countries | | CANCELLED | This status indicates the shipment has been cancelled either by the connector or by the marketplace. This is a terminal status | Cancelled | Standard Cancelled order, all payments and statuses to be updated as per our standard abstraction methods |

More Statuses Information:

As it was confirmed with the Amazon team we can’t just call all orders but have to do so status by status below you can see the general business requirements:

• We need to receive all ACCEPTED orders as this is the place where we start external communication with clients as well OR is a trigger for us to Acknowledge automatically
• Once the order is Acknowledged (CONFIRMED) we need to track this status so we can make sure orders are updated as Ready For Shipping in Hemi. In phase one this will not be a trigger for anything and just keep clarity in Hemi but in future states this will be the blocker for triggering any further requests (in the likes of PACKAGE CREATED, PICKUP_SLOT_RETRIEVED and SHIPLABEL_GENERATED)
• SHIPPED & DELIVERED - purely informational - SHIPPED is to confirm our Shipment was a success, DELIVERED is to track that it got to the end buyer. This is not mandatory but it will be a nice to have (for more info please refer to the Amazon Smart Connect - Dispatch Shipments document)
• CANCELLED - There is the option for a whole Shipment to get fully cancelled as opposed to changed and provided as a new ACCEPTED one. We have to track this so we can successfully update any such Orders
• From perspective of flows - We are not expecting to constantly track for “new” orders (such that don’t exist in Hemi) across all statuses. This will be only for ACCEPTED and CANCELLED.

The way I envision this is the 2 statuses we have to track by getting all shipments are ACCEPTED and CANCELLED. For everything else we will employ the getShipment: Amazon Smart Connect - Get Shipment

<v1.5> 

<v1.4>
We should also start downloading the “SHIPPED” status for information and updating purposes. There are parts of Amazon (UAE in this case for example) that the Shipment is not mandatory to be sent… as such we will not be sending this for UAE which means we have no way to actually mark an order as Shipped in Hemi. To cover for this we need to start pulling down the SHIPPED status too purely for information perspective. We should follow everything per the abstraction when we receive a SHIPPED order and update status fields mostly (like Fulfillment Status)
</v1.4>

<v1.5> We need to have in mind that possibly there will be negative values for the discounts we should be saving on order/order item level. We need to always save positive values in Hemi </v1.5>

Note: This is just as general info as to why we are not creating a standard Hemi Get Modified Orders call

Example mapping (please see attached the Order Fulfilment API doc and search for the schema for “getShipments”)

Order Fulfillment APIs.docx

The mapping itself is in excel spreadsheet as the table structure here was making the page too heavy

<v1.5>

Amazon Smart Connect Order Download Map_v2.xlsx

</v1.5>

<v1.1>

We have added additional mapping as we want to store the shipments.id into a new field in Orders Amazon > Smart Connect Shipment ID the excel file is updated as well.

</v1.1>

<v1.2>

Please note that there are a few specifics in the Mapping we need to take care off:

• Object “TaxBreakup” is not mandatory and if not present it should not break our calculations and we should simply treat it as there is no such value to add/remove
• Node “ChargeType” should not be case sensitive - we can receive small or capital letters
• ADDITION: we need to add mapping for Shipping Address in case this is missing. Those are to be the following:
  • Orders > Shipping Buyer Name: Amazon Buyer
  • Orders > Shipping Street 1: Amazon Shipping Street 1
  • Orders > Shipping City: Amazon City
  • Orders > Shipping Country Code: AE
  • Orders > Buyer mail: amazonBuyer@amazonbuyer.com
  • Orders > Shipping Phone: 000000000
  • Orders > Shipping State Province: Amazon State Province
  • Orders > Shipping Postal Code: Amazon Postcode

</v1.2>

<v1.3>

As a new information from Amazon it turns out when we read the object LineItems and we need to consume the charges from it we need to treat the chargeType: “product” as value for the whole line. This means that whatever we are trying to store as unit values (mainly Order Item > Item Trans Price ) we need to divide this by the value of numberOfUnits from the same LineItem object. We need to round the result value to the nearest 2 decimal points (e.g. 10.48)

</v1.3>

<v1.4>

As per update from Amazon we should also amend slightly the way we split the Shipping cost per Product in Hemi. In the case we receive a SHIPPING charge per the product line everything is great and we don’t have to do any changes. Whatever we’ve received there, great.

Now, the problem comes from the fact Amazon said they most probably will never provide shipping cost per product BUT they are also splitting the shipping cost differently than us (which in essence makes difference for reporting and refunding purposes).

The current state is that as part of our abstractions we split the shipping cost evenly per each product (we have 10 cost and 2 SKUs we don’t look at price or quantity - just split by 2 OR we have the option to see the price and split proportionately to the price of the items).

Amazon split everything per quantity. If we have an order with 10 shipping cost and 2 SKUs (SKU1111 x 1 qty and SKU2222 x 4 qty) they will sum up all qty (5 in this case) and split the cost as cost per quantity (meaning SKU1111 will have shipping cost 2 where SKU2222 will have shipping cost 8). This is important because then when Amazon handle returns they automatically also refund the shipping cost PER quantity returned. In other words if there is a return for SKU2222 x 3 quantity we will need to be able to refund 6 cost for this product. This is of course for the GetReturns script to handle but the GetShipments needs to ensure first the shipping cost is set the right way so then all of our refund processors can work as expected and at all times Hemi will keep the correct values for these orders

</v1.4>

Please note Amazon Smart connect is a marketplace that works with Acknowledgements. This means we want to incorporate the abstraction on Acknowledgement download as well - make the checks for automatic Acceptance or not and create records if needed, etc.

The flag for the Automatic Acceptance is our Account > Acknowledgement Option = “Automatic Acknowledgement”

Everything that is not specifically mentioned should be following our standard abstractions for orders downloads and cancellations from here:

Order management general requirements