Update or cancel shipment
Learn how to update or cancel submitted shipment requests.
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
, andsellingParty.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
, andsellingParty.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
andFailure
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"
}
}
]
}
Updated about 23 hours ago