Shipments

kind: "carrier" hands the order to a delivery company (needs delivery:dispatch); kind: "driver" gives it to the store's driver (needs orders:assign).

Carrier. Only a ready order with no shipment can be handed off. The shipment is reserved before the carrier is called, so a second dispatch of the same order is refused (409 ORDER_HAS_SHIPMENT) and never reaches the carrier.

What the carrier's answer proves decides the outcome:

• accepted — the carrier created the parcel. When the company auto-validates and the carrier needs a separate validation, it is validated too; a refused validation is reported in validationError and kept in the shipment's history.
• refused — the carrier refused it, the credentials failed, it was throttled, or it could not be reached: nothing was created and the order is ready again.
• unknown — the carrier may have created it (a timeout, a server error). It is never sent again automatically: resolve it with POST /shipments/{id}/resolve.

Driver. The store's own driver has no carrier to call: the shipment is accepted at once, and the driver's fee for the order's wilaya (0 where none is set) is frozen on it. The driver is not a carrier and has no stop desks: the shipment is always home delivery to the order's street address — an order whose customer chose a stop desk keeps that choice and its price, and the driver brings it to the door (deliveryType: "stop_desk" is refused). Only a ready order with no shipment and a street address (400 MISSING_ADDRESS), and a driver who is not inactive. The driver's progress is then reported with POST /shipments/{id}/events.

The same handoff as POST /orders/{id}/shipment, for up to 100 orders and one company, with one result per order. The carrier's bulk creation is used when it has one.

Only a ready order with no shipment can be handed off. The shipment is reserved before the carrier is called, so a second dispatch of the same order is refused (409 ORDER_HAS_SHIPMENT) and never reaches the carrier.

What the carrier's answer proves decides the outcome:

• accepted — the carrier created the parcel. When the company auto-validates and the carrier needs a separate validation, it is validated too; a refused validation is reported in validationError and kept in the shipment's history.
• refused — the carrier refused it, the credentials failed, it was throttled, or it could not be reached: nothing was created and the order is ready again.
• unknown — the carrier may have created it (a timeout, a server error). It is never sent again automatically: resolve it with POST /shipments/{id}/resolve.

The same handoff as POST /orders/{id}/shipment with kind: "driver", for up to 100 orders and one driver, with one result per order: accepted or refused (never unknown).

The store's own driver has no carrier to call: the shipment is accepted at once, and the driver's fee for the order's wilaya (0 where none is set) is frozen on it. The driver is not a carrier and has no stop desks: the shipment is always home delivery to the order's street address — an order whose customer chose a stop desk keeps that choice and its price, and the driver brings it to the door (deliveryType: "stop_desk" is refused). Only a ready order with no shipment and a street address (400 MISSING_ADDRESS), and a driver who is not inactive. The driver's progress is then reported with POST /shipments/{id}/events.

The shipment with its full history (carrier statuses as reported, and what Wocart concluded from them) and the actions available now.

Changes the customer's details, the destination, the cash to collect, the weight or fragility — at the carrier first, then in Wocart: the order's contact and destination (with its customer, like an order edit) and the shipment's cash, weight and fragility. Only before the parcel leaves (and, at a carrier that validates separately, before validation). A new destination needs both wilayaId and communeId.

• lookup — ask the carrier for a parcel with this order's number (carriers that support it). not_found leaves the shipment unresolved.
• attach — the parcel was found at the carrier: record its tracking number.
• release — the carrier has no parcel: the shipment is removed and the order is ready to hand off again.

For carriers that hold a created parcel until it is validated (EcoTrack, NOEST). After validation it can no longer be edited or cancelled.

Undo a shipment that never reached the customer, so the order can be handed off again: a carrier parcel is cancelled at the carrier first (unless the carrier already cancelled it); a driver's order is taken back from the driver. Refused once it is out for delivery. A carrier shipment needs delivery:dispatch, a driver's orders:assign.

Fetched from the carrier for the merchant: carrier labels sit behind the company's credentials or an expiring link.

A request the courier may decline; it is noted in the history and changes nothing until the carrier reports the return.

After a failed attempt (NOEST). Noted in the history.

EcoTrack's return confirmation, then the return is recorded: the goods go back in stock and the customer's spend is rolled back.

Records every status the carrier reports that the shipment does not have yet; a status already recorded (by webhook or an earlier sync) is not recorded twice.

What the merchant saw. On a driver's shipment: the driver's progress (out_for_delivery, failed_attempt, delivered, returned) — needs orders:assign. On a carrier shipment only returned: the goods are back with the merchant (the carrier alone can say a parcel was delivered) — needs delivery:dispatch.