Create Shipment

Ships one or more order items from a chosen inventory source. The same eligibility checks as the admin Shipment screen apply (the order must not be closed or marked fraud). Each item's requested quantity is validated against its still-shippable quantity, qty_to_ship, AND against the inventory available at the chosen source before the shipment is created.

For composite products (bundle, configurable, grouped), the requested quantity is split across the line's component items, and each component's own shippable quantity and stock at the chosen source are validated — so a shipment can't be created for more component stock than is physically available.

Endpoint

Endpoint	Method
/api/admin/orders/{orderId}/shipments	POST

Request body

Field	Type	Required	Notes
source	integer	yes	Inventory source id all items ship from.
items	array of { orderItemId, inventorySourceId, quantity }	yes	At least one entry with quantity > 0.
carrierTitle	string	no	Free-form carrier label (e.g. UPS).
trackNumber	string	no	Tracking number.

Errors

HTTP	Lang key	Message
422	bagistoapi::app.admin.order.actions.shipment.closed	Closed orders cannot be shipped.
422	bagistoapi::app.admin.order.actions.shipment.fraud	Fraud orders cannot be shipped.
422	bagistoapi::app.admin.order.actions.shipment.nothing-to-ship	There is nothing to ship on this order.
422	bagistoapi::app.admin.order.actions.shipment.no-permission	You do not have permission to ship orders.
422	bagistoapi::app.admin.order.actions.shipment.source-required	Inventory source is required.
422	bagistoapi::app.admin.order.actions.shipment.items-required	At least one item with a positive quantity is required.
422	bagistoapi::app.admin.order.actions.shipment.qty-exceeds	Requested quantity (:requested) exceeds available quantity (:available) for SKU :sku.
422	bagistoapi::app.admin.order.actions.shipment.inventory-insufficient	Inventory at the selected source is insufficient for SKU :sku.
422	bagistoapi::app.admin.order.actions.shipment.failed	Could not create the shipment.

Sample 422 response

{
    "type": "/errors/422",
    "title": "Bad Request",
    "status": 422,
    "detail": "Inventory at the selected source is insufficient for SKU WS-12-S."
}