Implementation reference
Amazon Vendor Shipments API: preflight the payload before the 202 response
The Vendor Retail Procurement Shipments API exchanges shipment-related documents for Amazon vendors. SubmitShipmentConfirmations accepts one or more shipment confirmations, but an HTTP acceptance response is not the same as physical receiving accuracy.
Direct answer: Validate JSON syntax and the current Amazon OpenAPI model first; then apply documented shipment-type, timing, identifier, carton, and item checks; finally reconcile the payload with the accepted PO, pack output, labels, and transport documents. Treat HTTP 202 as accepted for processing, not proof that the shipment is correct.
Validate against the current model first
Amazon publishes the Vendor Shipments OpenAPI model. Shipment Sentry keeps a source-attributed research copy so model changes can be reviewed, tested, and tied to a rule-pack date instead of silently appearing in production.
The runtime validator reports paths such as:
$.shipmentConfirmations[0].sellingParty.partyId
$.shipmentConfirmations[0].shipmentDetails.shipmentIdentifiers[0].shipmentIdentifier
$.shipmentConfirmations[0].shippedItems[2].itemSequenceNumber
An exact path makes the finding actionable for an integration developer and prevents guesswork across repeated confirmation objects.
Business rules beyond JSON schema
The current Submit shipment confirmation tutorial adds operational rules that a JSON Schema alone cannot express completely:
- Submit confirmations before the product is received.
- Separate materially distinct deliveries as documented.
- Supply a BOL value for FTL/LTL workflows where required.
- Confirm carton/package detail and tracking for small-parcel flows where applicable.
- Keep shipment identifiers and SSCCs unique for their documented periods.
- Reuse the original shipment identifier and selling party for a replacement as instructed.
- Put perishable detail at the relevant packed-item level.
Each of these checks carries a source class and review date. Account-specific requirements stay warnings until the current account guide establishes them.
Why schema-valid JSON can still be wrong
A schema can confirm that shippedQuantity is a number; it cannot prove the warehouse packed that quantity. It can confirm that an SSCC has a field; it cannot scan the label on the carton. It can confirm a BOL string exists; it cannot prove it matches the carrier document.
Use a second-source gate for:
| Payload field | Authoritative comparison |
|---|---|
| purchaseOrderNumber / item identity | Accepted PO and acknowledgement state |
| shippedQuantity and unitOfMeasure | WMS pack confirmation |
| container identifiers | Decoded physical label scans |
| carton count and tracking | Carrier manifest and pack closeout |
| BOL, PRO, ARN, dates | TMS and transport documents |
Response and replacement handling
Store the exact submitted content hash, internal preflight result ID, rule-pack version, API request ID, and subsequent transaction-status result. A retry after a timeout must not accidentally create a semantically different confirmation. Generate and enforce your own idempotency and replacement discipline around the documented API behavior.
Common questions
Does Shipment Sentry call SP-API?
No. The current product validates before submission and therefore does not need access to a vendor’s SP-API credentials.
Is the whole Amazon schema implemented?
The public model is retained as a research fixture. Runtime validation focuses on the high-value required fields and documented business rules covered by tested fixtures; the report identifies the rule-pack version so the boundary is visible.
Primary sources
Public sources cannot establish every account-specific EDI rule. Current Vendor Central documentation and your trading-partner agreement remain controlling.