Shipments
Overview
Shipments: N:N items with the order, tracking, label and dispatch.
A shipment is the package that takes one or more order items to the buyer. marketapi syncs the shipment, tracking and dispatch deadline, and you request labels and dispatch through jobs.
The whole journey: The order lifecycle.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/shipments | List shipments |
GET | /v1/shipments/{shipmentId} | Get shipment |
GET | /v1/shipments/{shipmentId}/tracking | Get tracking |
GET | /v1/shipments/{shipmentId}/dispatch-options | Get dispatch options |
POST | /v1/shipments/{shipmentId}/label-requests | Request label |
POST | /v1/shipments/{shipmentId}/dispatches | Dispatch shipment |
POST | /v1/shipments/{shipmentId}/actions | Run shipment action |
Rules
- N:N with lines. Each shipment item links an order line to a quantity. One shipment carries lines from several orders, and one line can ship in several shipments.
- The label is a confidential file (
pdforzpl). It never has a public URL. You download it through asset, and every read is logged. - The invoice blocks shipping. With
invoice_requiredinstatusReasons, label and dispatch answer409until the invoice is accepted. - Commands are jobs. Label, dispatch and actions answer
202with a job. Without marketplace support:422 CAPABILITY_UNSUPPORTED, and no job is created.
States
status: pending, ready_to_ship, shipped, delivered, not_delivered, cancelled. The order fulfillmentStatus follows. When the shipment moves to shipped, the reserved stock is written off (order policy).
Webhooks
shipment.updated (any change) and shipment.label_ready (carries assetId and format).