Records what shipped for an order (orderId) or one of its fulfillment orders (fulfillmentOrderId), in one transaction: the shipping log and its lines, the fulfillment-order and order credits, and the stock moved from the source location through the warehouse queue. A shipment is a recorded fact: it is never refused for missing stock; a source that held less on record than it shipped is corrected in the same transaction and answered as an inventory_shortfall warning. Items name an order line, a fulfillment-order line, or the product the order sold; anything else is 422. An externalId already on the channel (or, without an externalId, the same tracking number on a live shipment of the order) follows onDuplicate (default update: the body is applied as a PATCH whose items are the full list; error: 409; skip: the stored shipment). Never calls a carrier.

Scope: shipments:write, channel:write or admin.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.