Submit or update a shipment request

❗

Important

SubmitShipments is available for WePay (Collect) vendors in North American and EU marketplaces. The operation only applies to standard pallets. Non-standard pallets are not supported.

The SubmitShipments operation enables WePay (Collect) vendors to submit requests for the pickup of their shipments by Amazon. You can also update or cancel submitted requests with this operation.

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 Vendor Retail Procurement Shipments role assigned to your developer profile.

Create a shipment request

To create a new shipment request with the SubmitShipments operation, complete the following:

Step 1. Check that the purchase order is confirmed.

Unconfirmed purchase orders cause the request to fail.

Step 2. Add required values to the request.

Include all required fields in the request. Set the following fields with the appropriate values:

For example:

{
  "shipments": [
    {
      "vendorShipmentIdentifier": "00050003",
      "transactionType": "New",
      "transactionDate": "2019-08-07T19:56:45.632",
      "shipmentFreightTerm": "Collect",
      "sellingParty": {
        "partyId": "PQRSS"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "999US"
      },
      "shipToParty": {
        "partyId": "ABCDF"
      },
      "shipmentMeasurements": {
        "totalCartonCount": 30,
        "totalPalletStackable": 30,
        "totalPalletNonStackable": 30,
        "shipmentWeight": {
          "unitOfMeasure": "Kg",
          "value": "120.45"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "2.4"
        }
      },
      "collectFreightPickupDetails": {
        "requestedPickUp": "2019-08-07T19:56:45.632"
      },
      "purchaseOrders": [
        {
          "purchaseOrderNumber": "1BBBAAAA"
        },
        {
          "purchaseOrderNumber": "1BBBACCC"
        }
      ]
    }
  ]
}

Step 3. Submit the request.

Call the SubmitShipments operation with the request body you built in Step 2.

Use the Shipments page in Vendor Central or the Vendor Transaction Status API to verify the status of your shipment request. If the status of the posted request doesn't appear after 30 minutes, submit a support case by navigating to Vendor Central > Support > Contact Us > API Integration.

After you submit your request, you can call the GetShipmentDetails operation to obtain routing instructions, which you'll then use to submit the Advance Ship Notice (ASN) with the SubmitShipmentConfirmations operation.

Update a shipment request

To update a shipment request, provide the vendorShipmentIdentifier of the existing shipment you want to update. Modify fields as needed, noting the following constraints:

• The vendorShipmentIdentifier, buyerReferenceNumber, and sellingParty.partyId must remain identical to the original request.
• You can only modify requestedPickUp after a carrier is assigned.

When ready, submit the request.

Cancel a shipment request

You can cancel a shipment request both before and after a carrier is assigned and routing is scheduled. To cancel a previously submitted shipment request, match the following fields from the original request:

• vendorShipmentIdentifier
• buyerReferenceNumber
• sellingParty.partyId
• shipFromParty.partyId
• shipToParty.partyId

Set the transactionType to Cancel and submit the request. For example:

{
  "shipments": [
    {
      "vendorShipmentIdentifier": "00050003",
      "buyerReferenceNumber": "1234567",
      "transactionType": "Cancel",
      "transactionDate": "2019-08-07T19:56:45.632",
      "shipmentFreightTerm": "Collect",
      "sellingParty": {
        "partyId": "PQRSS"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
      },
        "partyId": "999US"
      },
      "shipToParty": {
      "partyId": "ABCDF"
      }
    }
  ]
}