vendorShipments_SubmitShipments
Submit vendor shipment requests — the advance shipment notice, BEFORE goods ship (after dispatch use vendorShipments_SubmitShipmentConfirmations).
destructiveAmazon Seller (SP-API)sp.vendorShipments
Amazon write; blocks until the transaction reaches Success or Failure. Amazon SP-API · SubmitShipments · POST /vendor/shipping/v1/shipments Amazon SP-API · getTransaction · GET /vendor/transactions/v1/transactions/{transactionId} Gate: approve — interactive: show the change (Amazon's preview first where one exists), wait for an explicit approve; autopilot: only when the seller's own words asked for this change; otherwise ask.
Call it
In an AI client (MCP)
{
"name": "vendorShipments_SubmitShipments",
"arguments": {
"store": "myStore-US",
"shipments_payload": {}
}
}From code (Tool API)
curl -X POST https://api.sellersheetai.com/api/v1/tools/vendorShipments_SubmitShipments \
-H "Authorization: Bearer $SELLERSHEET_API_KEY" \
-H "Content-Type: application/json" \
-d '{"store":"myStore-US","shipments_payload":{}}'Early access — the Tool API is open on request, contact us.
Arguments
| Name | Type | Description |
|---|---|---|
storerequired | string | the store ref `<store>-<CC>` (name-country, e.g. 'myStore-US') — one of get_user_context's store_refs, verbatim. |
shipments_payloadrequired | object | {"shipments": [Shipment, …]}. Per Shipment, required: vendorShipmentIdentifier (unique, unused in the last 365 days), transactionType (New | Cancel), transactionDate (ISO-8601), sellingParty, shipFromParty and shipToParty — each a Party (partyId, address, taxRegistrationDetails; full shape in the Body block below). Optional: buyerReferenceNumber; currentShipmentStatus (Created | TransportationRequested | CarrierAssigned | Shipped); shipmentFreightTerm (Collect | Prepaid); shipmentMeasurements {totalCartonCount, totalPalletStackable, totalPalletNonStackable, shipmentWeight {unitOfMeasure G | Kg | Oz | Lb, value}, shipmentVolume {unitOfMeasure CuFt | CuIn | CuM | CuY, value}}; collectFreightPickupDetails {requestedPickUp, scheduledPickUp, carrierAssignmentDate}; purchaseOrders: [{purchaseOrderNumber, purchaseOrderDate, shipWindow, items: [{itemSequenceNumber ('001', '002', …) required, buyerProductIdentifier (ASIN) or vendorProductIdentifier, shippedQuantity {amount, unitOfMeasure Cases | Eaches, unitSize, totalWeight {unitOfMeasure POUNDS | OUNCES | GRAMS | KILOGRAMS, amount}} required, maximumRetailPrice {currencyCode, amount}}]}]; containers: [{containerType carton | pallet, containerSequenceNumber, containerIdentifiers: [{containerIdentificationType SSCC | AMZNCC | GTIN | BPS | CID, containerIdentificationNumber}] required, trackingNumber, dimensions {length, width, height, unitOfMeasure In | Ft | Meter | Yard}, weight {unitOfMeasure G | Kg | Oz | Lb, value}, tier, block, innerContainersDetails, packedItems: [{itemSequenceNumber, buyerProductIdentifier or vendorProductIdentifier, packedQuantity {amount, unitOfMeasure Cases | Eaches, unitSize}, itemDetails {purchaseOrderNumber, lotNumber, expiry}}]}]; importDetails {methodOfPayment PaidByBuyer | CollectOnDelivery | DefinedByBuyerAndSeller | FOBPortOfCall | PrepaidBySeller | PaidBySeller, sealNumber, route {stops: [{functionCode PortOfDischarge | FreightPayableAt | PortOfLoading, locationIdentification, arrivalTime, departureTime}]}, importContainers (≤64 chars), billableWeight, estimatedShipByDate, handlingInstructions Oversized | Fragile | Food | HandleWithCare}; transportationDetails {shipMode TruckLoad | LessThanTruckLoad | SmallParcel, transportationMode Road | Air | Ocean, shippedDate, estimatedDeliveryDate, shipmentDeliveryDate, carrierDetails {name, code (SCAC), phone, email, shipmentReferenceNumber}, billOfLadingNumber}; shipmentStatusDetails: [{shipmentStatus Created | TransportationRequested | CarrierAssigned | Shipped, shipmentStatusDate}]; shipmentCreateDate, shipmentConfirmDate, packageLabelCreateDate (ISO-8601). Full tree: https://developer-docs.amazon.com/sp-api/docs/vendor-shipments-api-v1-reference |
Result
Every tool answers {notification, data, human_action}; data carries:
data.transactionId— the transaction, already final when this returns.data.status— SUCCESS, or Failure with data.errors [{code, message, details}].
Body (Amazon schema; SubmitShipments): {shipments: [Shipment]}, each item
vendorShipmentIdentifier*: string
transactionType*: New | Cancel
transactionDate*: string (date-time)
sellingParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}
shipFromParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}
shipToParty*: {address: {name*, addressLine1*, addressLine2, addressLine3, city, county, district, stateOrRegion, postalCode, countryCode*, phone}, partyId*, taxRegistrationDetails: [{taxRegistrationType*, taxRegistrationNumber*}]}
currentShipmentStatus: Created | TransportationRequested | CarrierAssigned | Shipped
shipmentFreightTerm: Collect | Prepaid
+ 12 more: buyerReferenceNumber, currentshipmentStatusDate, shipmentStatusDetails, shipmentCreateDate,
shipmentConfirmDate, packageLabelCreateDate, shipmentMeasurements, collectFreightPickupDetails,
purchaseOrders, importDetails, containers, transportationDetails
Full schema: the Docs link above.Gotchas
- A Shipment has NO top-level items array — line items live under purchaseOrders[].items. The item identifier here is buyerProductIdentifier, not amazonProductIdentifier (that name belongs to the shippedItems of vendorShipments_SubmitShipmentConfirmations). HTTP 502 = still Processing after 60 s; the error names the transactionId — check it with vendorTransactionStatus_getTransaction before resubmitting.