Amazon Vendor Procurement Shipment

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Hemi need to have the capabilities to submit the shipment confirmation to Amazon which is the actual shipping update. The flow is asynchronous and after each request we will have to wait for a response. There will be two type of shipments one where Amazon collects the shipment and one where the vendor ship the shipment to the Amazon Warehouse.We need to have control over the type which will be handled with an additional flag in Account Amazon. We will also have the case where a single vendor supports both types of shipments which means we will first have to SubmitShipments then GetShipments and once the shipment is collected by Amazon to make SubmitShipmentConfirmations.

SubmitShipments is the operation for Collect or WePay vendors which submit requests for the pickup of their shipments by Amazon. When we are submitting a shipment request the requested pickup date must be a minimum of two business days after the current date.

GetShipments is the operation where we are obtaining the Amazon Reference Number for the Shipment which we have already created and which we will have to use for SubmitShipmentConfirmations

SubmitShipmentConfirmations is the operation which send the shipment confirmation to Amazon what we will be shipping. With the shipment confirmation Amazon can efficiently receive and process our shipments. It contains information about the items being shipped, including purchase order number, ship date, estimated delivery date, lot number, expiration date, and the Serial Shipping Container Code (SSCC). By sending a valid and timely shipment confirmation, Amazon can correctly anticipate the shipments.

Based on the terms which the Vendor sign with Amazon we will have 2 cases:

Case #1: Vendor is shipping everything to Amazon using 3rd party logistic partner in this case we have to just create a sing SubmitShipment to notify Amazon what and where we are shipping.

Case#2 Vendor is using Amazon for collection and delivery in this case the vendor first will have to make SubmitShipmentConfirmations. The second step will be automatic based on the Shipment Status which we will be getting with the **GetShimentDetails.

<v1.5> The cases are controlled by the Channel Amazon > Vendor Freight Term. If we have Channel Amazon > Vendor Freight Term = Collect we want to use Case 1 - SubmitShipment If we have Channel Amazon > Vendor Freight Term = Prepaid we want to use Case 2 - SubmitShipmentConfirmations </v1.5>**

Both types of shipment support partial shipping. All validations, triggers and standardizations which are not mentioned here are as per : Order management general requirements

Order General Shipment

SubmitShipments

We want to push only 1 shipment for single request.

API Call: POST /vendor/shipping/v1/**shipments**

Docs: https://developer-docs.amazon.com/sp-api/docs/vendor-shipments-api-v1-reference#submitshipmentconfirmations

Sample Request: POST **/vendor/shipping/v1/shipments** Body:

{
    "shipments": [
        {
            "vendorShipmentIdentifier": "497",
            "transactionType": "New",
            "buyerReferenceNumber": "1",
            "shipmentFreightTerm": "Collect",
            "transactionDate": "2025-04-09T12:11:24Z",
            "sellingParty": {
                "partyId": "7E89F"
            },
            "shipFromParty": {
                "address": {
                    "name": "Pipercross Location UK",
                    "addressLine1": "9 Sketty Close",
                    "city": "Northampton",
                    "postalCode": "NN4 7PL",
                    "countryCode": "GB"
                },
                "partyId": "1"
            },
            "shipToParty": {
                "partyId": "LBA5"
            },
            "shipmentMeasurements": {
                "totalPalletStackable": 0,
                "totalCartonCount": 0,
                "totalPalletNonStackable": 0,
                "shipmentWeight": {
                    "unitOfMeasure": "G",
                    "value": 1000
                }
            },
            "purchaseOrders": [
                {
                    "purchaseOrderNumber": "1HTWUWAJ_test",
                    "purchaseOrderDate": "2025-04-07T05:08:45Z",
                    "items": [
                        {
                            "itemSequenceNumber": 1,
                            "buyerProductIdentifier": "B08P3M3QK9",
                            "vendorProductIdentifier": "5056195624083",
                            "shippedQuantity": {
                                "amount": 2,
                                "unitOfMeasure": "Eaches"
                            }
                        }
                    ]
                }
            ],
            "containers": [
                {
                    "containerType": "",
                    "containerSequenceNumber": "01",
                    "containerIdentifiers": [
                        {
                            "containerIdentificationType": "SSCC",
                            "containerIdentificationNumber": "1232141515"
                        }
                    ],
                    "trackingNumber": "12345678",
                    "dimensions": {
                        "length": "3.9370",
                        "width": "3.9370",
                        "height": "3.9370",
                        "unitOfMeasure": "In"
                    },
                    "weight": {
                        "unitOfMeasure": "G",
                        "value": 1000
                    },
                    "packedItems": [
                        {
                            "itemSequenceNumber": 1,
                            "buyerProductIdentifier": "B08P3M3QK9",
                            "vendorProductIdentifier": "5056195624083",
                            "packedQuantity": {
                                "amount": 2,
                                "unitOfMeasure": "Eaches"
                            },
                            "itemDetails": {
                                "purchaseOrderNumber": "1HTWUWAJ_test"
                            }
                        }
                    ]
                }
            ]
        }
    ]
}

Mapping: Please note everything with Hemi Field = N/A we exclude from the payload.

Limits:

New enum Field in Channel Amazon called Freight Term with two options: ”Collect” ”Prepaid”</v1.4> | | | sellingParty | | | | Yes | | | | | | partyId | | | Yes | Order Amazon >Purchase Order Selling Party | New field under new tab “Amazon Vendor” | | | shipFromParty | | | | Yes | Order Shipment > Ship From | New Field - In order to control the ship from location we want to use our Locations structure and use the Location address.

In the location we will store all the details for the Ship From Party and we will add each location into the Account Location table.

We will be able to set if we want to have a default account location and based on the selection of the user in the new Order Ship Modal we want to pick the location from the Order Shipment > Ship From | | | | address | | | No | | | | | | | name | | No | Location > Name | | | | | | addressLine1 | | No | Location > Street1 | | | | | | city | | No | Location > City | | | | | | stateOrRegion | | No | N/A | | | | | | postalCode | | No | Location > Post Code | | | | | | countryCode | | No | Location > Country 2 char code | | | | | partyId | | | Yes | Location > Vendor ID | New Field | | | shipToParty | | | | | | | | | | partyId | | | Yes | Order > Shipping Address ID | | | | shipmentMeasurements | | | | No | | | | | | totalPalletStackable | | | No | | If we have Order Shipment Packages > Package Type = “Pallet” we count all records for the order with this type. If we do not have a type we push empty node | | | | totalCartonCount | | | No | | We count the Order Shipment Row Boxes | | | | totalPalletNonStackable | | | No | <v1.4>“0” | Hardcoded as 0<v1.4> | | | | shipmentWeight | | | | | | | | | | unitOfMeasure | | No | “G” | Hardcoded as “G” since grams are the default measure in Hemi | | | | | value | | No | SUM(Order Shipment Packages >Weight) | <v1.4> Case Pallet Type: If we have a container type = pallet we want to calculate the weight for each pallet and sum them. Each pallet will have its own weight in the payload.

Case Box Type: If we have a container type = carton we want to calculate the weight for each carton and sum them. Each carton will have its own weight in the payload. In this case we must not have pallet in the shipment.

Case Package Type: If we have a container type = “” we want to calculate the weight for the package it will be always one container </v1.4> | | | | shipmentVolume | | | | | | | | | | unitOfMeasure | | No | <v1.4>”CuM” | Hardcoded as “CuM” which is Cubic Meter | | | | | value | | No | SUM(Order Shipment Packages > Length(cm)Order Shipment Packages > Width(cm)Order Shipment Packages >Height(cm)) | In order to calculate the volume we need to multiply all the dimensions line HeightWidthLength

There will be 3 cases in the way we want to calculate the volume.

Case Pallet Type: If we have a container type = pallet we want to calculate the volume for each pallet and sum them. Each pallet will have its own dimensions in the payload.

Case Box Type: If we have a container type = carton we want to calculate the volume for each carton and sum them. Each carton will have its own dimensions in the payload. In this case we must not have pallet in the shipment.

Case Package Type: If we have a container type = “” we want to calculate the volume for the package it will be always one container.

Since the unit will be Cubic meter and we will calculate in cubic centimeter we will have to convert them like cubic meters = cubic centimeters ÷ 1,000,000

</v1.4> | | | collectFreightPickupDetails | | | | | | | | | | requestedPickUp | | | No | N/A | | | | | scheduledPickUp | | | No | N/A | | | | | carrierAssignmentDate | | | No | N/A | | | | purchaseOrders | | | | | | | | | | purchaseOrderNumber | | | No | Orders > Marketplace Order Id | | | | | purchaseOrderDate | | | No | Orders > Order Created Time | Format - 2019-08-06T19:56:45.632 | | | | shipWindow | | | No | N/A | | | | | items | | | | | | | | | | itemSequenceNumber | | No | Product In Order > Order Item Line ID | Based on the Order Shipment Row > Order Item ID we want to map the correct product | | | | | buyerProductIdentifier | | No | Product In Order > Channel Item Id | | | | | | vendorProductIdentifier | | No | <v1.6>Product In Order > Item Transaction ID</v1.6> | Based on the Order Shipment Row > Order Item ID we want to map the correct product | | | | | shippedQuantity | | | | | | | | | | amount | No | Order Shipment Row > Quantity | We want to sum all Shipment Rows quantities | | | | | | unitOfMeasure | No | “Eaches” | Hardcoded as “Eaches” | | | | | | unitSize | No | N/A | | | | | | maximumRetailPrice | | | | | | | | | | currencyCode | No | N/A | | | | | | | amount | No | N/A | | | | containers | | | | No | | Please note if we do not have any Order Shipment Packages we exclude this node. | | | | containerType | | | No | Order Shipment Packages > Package Type | If we have Order Shipment Packages > Package Type = “Pallet” we push “pallet”

If we do not have Order Shipment Packages but we have Order Shipment Row Boxes we push “carton”

Else we push it empty. | | | | containerSequenceNumber | | | No | | We want to count and push for each container type a sequence number e.g. 001,002,003,004,005 for each next container with the same type. | | | | containerIdentifiers | | | No | | | | | | | containerIdentificationType | | No | Order Shipment Packages > Identification Type | New Field - Dropdown list the following enums SSCC AMZNCC GTON BPS CID | | | | | containerIdentificationNumber | | No | Order Shipment Packages > Identification Number | New Field | | | | trackingNumber | | | No | Order Shipment > Tracking Number | | | | | dimensions | | | | | | | | | | length | | No | > Length(cm) | New Field - We need to convert the centimeters to inches Order Shipment Packages > Length 0.393701 | | | | | width | | No | Order Shipment Packages > Width(cm) | New Field -We need to convert the centimeters to inches Order Shipment Packages > Width 0.393701 | | | | | height | | No | Order Shipment Packages >Height(cm) | New Field -We need to convert the centimeters to inches Order Shipment Packages > Height * 0.393701 | | | | | unitOfMeasure | | No | “In” | Hardcoded as “In” | | | | weight | | | | | | | | | | unitOfMeasure | | No | “G” | Hardcoded as “G” since grams are the default measure in Hemi | | | | | value | | No | Order Shipment Packages >Weight(g) | New Field | | | | tier | | | No | N/A | | | | | block | | | No | N/A | | | | | innerContainersDetails | | | | | | | | | | containerCount | | No | N/A | | | | | | containerSequenceNumbers | | No | N/A | | | | | packedItems | | | | | | | | | | itemSequenceNumber | | No | Product In Order > Order Item Line ID | Based on the Order Shipment Row > Order Item ID we want to map the correct product | | | | | buyerProductIdentifier | | No | Product In Order > Channel Item Id | | | | | | vendorProductIdentifier | | No | Product In Order > SKU | Based on the Order Shipment Row > Order Item ID we want to map the correct product | | | | | packedQuantity | | | | | | | | | | amount | No | <v1.3>

Order Shipment Packaging Row > Quantity

</v1.3> | <v1.3> If we have a package added we are to pick the information form the respective Packaging rows for each relevant package. If not the information should be picked from the standard Shipment Row Quantity </v1.3> | | | | | | unitOfMeasure | No | “Eaches” | Hardcoded as “Eaches” | | | | | | unitSize | No | N/A | | | | | | itemDetails | | | | | | | | | | purchaseOrderNumber | No | Order >Marketplace Order Id | | | | | | | lotNumber | No | N/A | | | | | | | expiry | No | N/A | | | | transportationDetails | | | | | | | | | | shipMode | | | No | N/A | | | | | transportationMode | | | No | N/A | | | | | shippedDate | | | No | N/A | | | | | estimatedDeliveryDate | | | No | N/A | | | | | shipmentDeliveryDate | | | No | N/A | | | | | carrierDetails | | | No | N/A | | | | | billOfLadingNumber | | | No | N/A | |

Sample Response: Status 200

{
    "payload": {
        "transactionId": "fd621aac-8dab-4885-b38e-21143679942e-20250409091213"
    }
}

Response Mapping:

Once we read the response using the Get Transaction Status If we receive success we want to set: Order > Status = “Shipped” or “Partially Shipped” Then we update the Order Shipment fields as per :

Order Shipment Functional Details

If we receive error we want to set: Order Shipment > Status = Error Store the relevant error message in Order Error table

Sample Error Response:

{
    "payload": {
        "transactionStatus": {
            "transactionId": "a7cbcbe3-05dd-4314-90ce-1cd917502c8d-20250409093326",
            "status": "Failure",
            "errors": [
                {
                    "code": "AmazonLinkAPI-926003",
                    "message": "Volume information is required for Shipment request<br> User Command Error:  Volume information is required for Shipment request Text:  Volume information is required for Shipment request Output Path: Transmission | RoutingRequest | ShipmentInformation | Volume TargetPath: Transmission | RoutingRequest | ShipmentInformation | Volume<br>",
                    "details": null
                },
                {
                    "code": "AmazonLinkAPI-926003",
                    "message": "Volume information is required for Shipment request<br> User Command Error:  Volume information is required for Shipment request Text:  Volume information is required for Shipment request Output Path: Transmission | RoutingRequest | ShipmentInformation | VolumeUnitOfMeasure TargetPath: Transmission | RoutingRequest | ShipmentInformation | VolumeUnitOfMeasure<br>",
                    "details": null
                }
            ]
        }
    }
}