Update or cancel shipment

❗

Important

SubmitShipments is only available in the North American and EU marketplaces.

The SubmitShipments operation enables Collect or WePay vendors to submit requests for the pickup of their shipments by Amazon.

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.

With this operation you can also update or cancel submitted requests. You can consolidate multiple orders that are ready to be shipped and request transportation through a single shipment request, thus saving time and lowering costs. When submitting a shipment request, the requested pickup date must be a minimum of two business days after the current date.

📘

Note

The SubmitShipments operation does not support submitting shipment requests for non-standard pallets.

Business requirements

• The shipment request must be submitted only when the corresponding purchase order is completely confirmed. If the purchase order is yet not confirmed, the shipment request fails to process.
• The requestedPickUp in the shipment request must be a minimum of two business days after the current date.
• All shipment request values are editable, except vendorShipmentIdentifier, buyerReferenceNumber, and sellingParty.partyId, which must remain identical for a successful update. You can modify all other fields in the shipment request before the carrier is assigned.
• You can only modify the requested pickup date in the shipment request after a carrier is assigned.
• You can cancel a shipment request both before and after a carrier is assigned and routing is scheduled.

Create or update shipment

When the transactionType for a shipment request is New, you can create a new request or update a previously submitted shipment request. Updates to an existing shipment request are done based on the Vendor Shipment ID. If a shipment with the provided vendor shipment ID already exists, an update operation occurs; otherwise, a new shipment is created.

• All shipment request values are editable, except vendorShipmentIdentifier,buyerReferenceNumber, and sellingParty.partyId which must remain identical for a successful update. You can modify all other fields in the shipment request before the carrier is assigned.
• The requested pickup date in the shipment request can only be modified after the carrier is assigned.

Cancel shipment

A shipment request with transactionType as Cancel enables you to cancel a previously submitted shipment request. To cancel a previously submitted shipment request, you must provide vendorShipmentIdentifier, buyerReferenceNumber, sellingParty.partyId, shipFromParty.partyId, shipToParty.partyId and transactionType as Cancel.

You can cancel a shipment request both before and after a carrier is assigned and routing is scheduled.

Verify successfully submitted shipment requests

You use 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 in Vendor Central by navigating to Vendor Central. Select Support, then Contact Us, and then API Integration.

📘

Note

The Transaction Status API only supports Processing and Failure status values for submitted Cancel Shipment requests.

Label flips

Label flips occur when the shipping method that is assigned during shipping label generation differs from the shipping method that is assigned during order creation.

Label flips are expected. During shipping label requests, our planning system might find a better shipping method than the shipping method that the purchase order originally assigned. However, you can greatly reduce the number of label flips by incorporating the following best practices into your processes:

• For single-package orders, don't include any container details in the body of shipping label creation request.
• Set sellingParty.partyId to the vendor code.
• Set shipFromParty.partyId to the warehouse ID.

Always submit shipping label requests between the carrier pick-up time of the previous day of the expected ship date and the actual day of shipping.

Create or update shipment request

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

Cancel shipment request

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