Amazon Vendor Procurement Shipment Confirmation

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.

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

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

SubmitShipmentConfirmations

We want to push only 1 shipment in a single request.

API Call: POST /vendor/shipping/v1/shipmentConfirmations

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

Sample Request: POST /vendor/shipping/v1/shipmentConfirmations Body:

{
  "shipmentConfirmations": [
    {
      "shipmentIdentifier": "1105",
      "shipmentConfirmationType": "Original",
      "shipmentType": "SmallParcel",
      "shipmentStructure": "MasterCase",
         "transportationDetails": {
        "carrierScac": "DHL",
        "carrierShipmentReferenceNumber": "60120203045256",
        "transportationMode": "Road",
        "billOfLadingNumber": "1105"

      },
      "amazonReferenceNumber": "44WZ162Z",
      "shipmentConfirmationDate": "2025-05-25T08:52:22.037Z",
      "shippedDate": "2025-05-28T12:52:22.037Z",
      "estimatedDeliveryDate": "2025-05-31T14:52:22.037Z",
      "sellingParty": {
                "partyId": "7E89F"
            },
            "shipFromParty": {
                 "address": {
                    "name": "Pipercross Location UK",
                    "addressLine1": "9 Sketty Close",
                    "city": "Northampton",
                    "postalCode": "NN4 7PL",
                    "countryCode": "GB"
                },
                "partyId": "7E89F"
            },
            "shipToParty": {
                "partyId": "MME2"
            },
      "shipmentMeasurements": {
        "grossShipmentWeight": {
          "unitOfMeasure": "G",
          "value": "0"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "0"
        },
        "cartonCount": 1,
        "palletCount": 0
      },
      "shippedItems": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": "B0C6BT63NS",
          "vendorProductIdentifier": "PP2008",
          "shippedQuantity": {
            "amount": 2,
            "unitOfMeasure": "Cases",
            "unitSize": 1,
            "totalWeight": {
              "unitOfMeasure": "POUNDS",
              "amount": "0"
            }
          },
          "itemDetails": {
            "purchaseOrderNumber": "44WZ162Z"
          }
        },
        {
          "itemSequenceNumber": "2",
          "amazonProductIdentifier": "B0C6BT63NR",
          "vendorProductIdentifier": "PP206",
          "shippedQuantity": {
            "amount": 1,
            "unitOfMeasure": "Cases",
            "unitSize": 1,
            "totalWeight": {
              "unitOfMeasure": "POUNDS",
              "amount": "0"
            }
          },
          "itemDetails": {
            "purchaseOrderNumber": "44WZ162Z"
          }
        }
      ],
      "cartons": [
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "60120203045256"
            }
          ],
          "cartonSequenceNumber": "1",
          "dimensions": {
            "length": "0",
            "width": "0",
            "height": "0",
            "unitOfMeasure": "In"
          },
          "weight": {
            "unitOfMeasure": "G",
            "value": "0"
          },
          "trackingNumber": "60120203045256",
          "items": [
            {
              "itemReference": "1",
              "shippedQuantity": {
                "amount": 2,
                "unitOfMeasure": "Cases",
                "unitSize": 1,
                "totalWeight": {
                  "unitOfMeasure": "POUNDS",
                  "amount": "1"
                }
              },
              "itemDetails": {
                "purchaseOrderNumber": "44WZ162Z"
              }
            },
              {
              "itemReference": "2",
              "shippedQuantity": {
                "amount": 1,
                "unitOfMeasure": "Cases",
                "unitSize": 1,
                "totalWeight": {
                  "unitOfMeasure": "POUNDS",
                  "amount": "1"
                }
              },
              "itemDetails": {
                "purchaseOrderNumber": "44WZ162Z"
              }
            }
          ]
        }
      ]
    }
  ]
}

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

OR ”LessThanTruckLoad” | If we have Order Packaging > Package Type = Pallet we use “LessThanTruckLoad” otherwise we use “SmallParcel"

| | | shipmentConfirmationType | | | | | | | No | “Original” | Hardcoded as “Original” | | | shipmentStructure | | | | | | | No | “MasterPallet” OR ”MasterCase” | If we have Order Packaging > Package Type = Pallet we use “MasterPallet” otherwise we use “MasterCase"

| | | amazonReferenceNumber | | | | | | | No | N/A | | | | transportationDetails | | | | | | | No | | | | | | transportationMode | | | | | | No | “Road” | Hardcoded as “Road” | | | | carrierScac | | | | | | No | Courier > SCAC
OR Order Shipment > Carrier | We want to be able to push the correct SCAC code by mapping Order Shipment > Carrier with Courier > Name | | | | carrierShipmentReferenceNumber | | | | | | No | Order Shipment > Tracking Number | We push this only if we have mapped SCAC code.

FYI - The field also known as PRO number is a unique number assigned by the carrier. It is used to identify and track the shipment that goes out for delivery. This field is mandatory for UA, CA, MX shipment confirmations. | | | | billOfLadingNumber | | | | | | No | Orders > Id | The Bill of Lading (BOL) number is a unique number assigned to each shipment of goods by the vendor or shipper during the creation of the Bill of Lading. This number must be unique for every shipment and cannot be a date/time or single character. The BOL number is mandatory in Shipment Confirmation message for FTL and LTL shipments, and must match the paper BOL provided with the shipment. Instead of BOL, an alternative reference number (like Delivery Note Number) for the shipment can also be sent in this field. | | | shipmentConfirmationDate | | | | | | | Yes | Current Date | Date on which the shipment confirmation was submitted. string (date-time) e.g. 2025-05-28T12:52:22.037Z" | | | shippedDate | | | | | | | No | <v1.1>Current Date</v1.1> | Date on which the shipment confirmation was submitted. string (date-time) e.g. 2025-05-28T12:52:22.037Z" | | | estimatedDeliveryDate | | | | | | | No | Orders Amazon > Earliest Delivery Date | e.g. "2025-05-31T14:52:22.037Z" <v1.1>If the date is missing we exclude it from the payload </v1.1> | | | sellingParty | | | | | | | Yes | | | | | | partyId | | | | | | Yes | Order Amazon >Purchase Order Selling Party | | | | shipFromParty | | | | | | | Yes | Order Shipment > Ship From | 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 | | | | shipToParty | | | | | | | Yes | | | | | | partyId | | | | | | Yes | Order > Shipping Address ID | | | | shipmentMeasurements | | | | | | | No | | | | | | grossShipmentWeight | | | | | | No | | | | | | | unitOfMeasure | | | | | No | “G” | Hardcoded as “G” since grams are the default measure in Hemi | | | | | value | | | | | No | SUM(Product in Order > Weight(g) * Product in Order >Quantity ) | Sum of all Order Items which are included in the shipment

If the weight is 0 we want to push empty string | | | | shipmentVolume | | | | | | No | | | | | | | unitOfMeasure | | | | | No | “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

SSCC AMZNCC GTON BPS CID | | | | | | containerIdentificationNumber | | | | Yes | Order Packaging > Identification Number | New Field | | | | | tier | | | | | No | N/A | | | | | | block | | | | | No | N/A | | | | | | dimensions | | | | | No | | | | | | | | length | | | | No | Order Packaging> Length(cm) | We need to convert the centimeters to inches Order Packaging > Length / 2.54 | | | | | | width | | | | No | Order Packaging> Width(cm) | We need to convert the centimeters to inches Order Packaging > Width / 2.54 | | | | | | height | | | | No | Order Packaging > Height(cm) | We need to convert the centimeters to inches Order Packaging > Height / 2.54 | | | | | | unitOfMeasure | | | | No | “In” | Hardcoded as “In” | | | | | weight | | | | | No | | | | | | | | unitOfMeasure | | | | No | “G” | Hardcoded as “G” since grams are the default measure in Hemi | | | | | | value | | | | No | Order Packaging >Weight(g) | New Field | | | | | cartonReferenceDetails | | | | | No | | | | | | | | cartonCount | | | | No | | Based on the package type and the number of packages we will have to Count the total boxes | | | | | | cartonReferenceNumbers | | | | No | | We want to push all cartonSequenceNumber which we have generated for the cartons like: "001", "002", "003", "004" | | | | | items | | | | | No | | | | | | | | itemReference | | | | Yes | shippedItems > itemSequenceNumber | Same as the shippedItems > itemSequenceNumber | | | | | | shippedQuantity | | | | Yes | | | | | | | | | amount | | | Yes | Order Shipment Packaging Row > Quantity | Since there is not quantity on the pallet we want to pick it from the boxes in the pallet | | | | | | | unitOfMeasure | | | Yes | “Eaches” | Hardcoded as “Eaches” | | | | | | | unitSize | | | No | N/A | |

Limits:

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
                }
            ]
        }
    }
}