Shipment status codes

Carriyo provides standardized shipment status codes that indicate the current stage of a shipment within the delivery process. Carriers across the world use different vocabularies; Carriyo normalizes them into the codes below so your downstream systems work against one model.

Key highlights

• Pre-shipping statuses track the shipment from creation to the point it's handed over to the carrier. Includes stages like draft, pending, and booked, and failure scenarios like error or cancelled_by_carrier. Note: draft is the pre-booking creation state; once a shipment is booked, it moves through the rest of the statuses below.
• Post-shipping statuses monitor the journey through the carrier network with states like in_transit, out_for_delivery, and delivered. Exceptions (suspended, missing) and return processes (ready_for_return, returned) are also covered.
• Final statuses mark the end of the lifecycle: delivered, returned, delivery_confirmed, return_confirmed.

Status flow

The canonical forward-shipment state machine.

                ┌───────┐
                │ draft │ ◄── created, not confirmed
                └───┬───┘
                    │ confirm
                    ▼
                ┌─────────┐
                │ pending │ ◄── awaiting carrier
                └────┬────┘
                     │
       ┌─────────────┼──────────────┬──────────────────┐
       ▼             ▼              ▼                  ▼
   ┌────────┐   ┌────────┐  ┌──────────────────┐  ┌─────────┐
   │ booked │   │ error  │  │cancelled_by_carr.│  │cancelled│
   └───┬────┘   └────┬───┘  └──────────────────┘  └─────────┘
       │             │            (final)            (final)
       │             └──── retry ───► pending
       ▼
   ┌──────────────┐
   │ ready_to_ship│ ◄── carriers requiring confirmation
   └──────┬───────┘
          ▼
      ┌─────────┐
      │ shipped │ ◄── handed to carrier
      └────┬────┘
           ▼
      ┌────────────┐
      │ in_transit │
      └─────┬──────┘
            │
       ┌────┼─────────────┐
       ▼    ▼             ▼
   ┌─────────┐ ┌──────────┐ ┌─────────┐
   │ delayed │ │suspended │ │ missing │
   └─────────┘ └──────────┘ └─────────┘
            │
            ▼
      ┌─────────────────┐
      │out_for_delivery │
      └────────┬────────┘
               │
        ┌──────┼──────────────────┐
        ▼      ▼                  ▼
   ┌───────────┐  ┌───────────────────────┐
   │ delivered │  │failed_delivery_attempt│
   │  (final)  │  └─────────┬─────────────┘
   └───────────┘            │
                       retry│ multiple failures
                  (→ OFD)   ▼
                       ┌────────────────┐
                       │ready_for_return│
                       └────────┬───────┘
                                ▼
                       ┌──────────────────┐
                       │return_in_transit │
                       └────────┬─────────┘
                                ▼
                          ┌──────────┐
                          │ returned │ (final)
                          └──────────┘

Edge cases

A few statuses appear outside the main forward flow:

• awaiting_customer_collection: for collection-point deliveries, the shipment lands in this state between in_transit and delivered while the customer comes to pick it up.
• out_for_collection and failed_collection_attempt: pre-shipping states that apply to reverse shipments, where the carrier collects the parcel from the customer (rather than delivering one).
• delivery_confirmed and return_confirmed: optional follow-up states layered on top of delivered / returned when the receiving party explicitly confirms.

Transition rules

• A shipment in pending can be cancelled by the merchant or cancelled_by_carrier after the carrier accepts and then declines it.
• An error is recoverable: fix the underlying issue and the shipment returns to pending for re-processing.
• failed_delivery_attempt retries back to out_for_delivery; after enough failures the carrier flags ready_for_return and the parcel goes back to the sender via return_in_transit → returned.
• Once a shipment lands in delivered, returned, cancelled, or cancelled_by_carrier, no further transitions occur.

Full list

Status code	Description	Phase
draft	The shipment has been created as a draft. It is not confirmed and will not be communicated to the carrier.	Pre-shipping
pending	The shipment has been confirmed by the merchant and is pending carrier acceptance and tracking number.	Pre-shipping
booked	The shipment has been successfully accepted by the carrier, and a tracking number (AWB) is generated.	Pre-shipping
error	There was an error in communicating the shipment to the carrier, requiring troubleshooting or manual edits.	Pre-shipping
ready_to_ship	Confirmation that the shipment is ready for carrier pick-up, applicable to carriers requiring this status.	Pre-shipping
failed_collection_attempt	The carrier attempted but failed to collect the shipment from the pickup location. Applies to reverse shipments.	Pre-shipping
cancelled_by_carrier	The carrier cancelled the shipment after acceptance, possibly due to capacity or coverage limits.	Pre-shipping
cancelled	The shipment was manually cancelled by a user in Carriyo. Final status.	Pre-shipping
out_for_collection	The carrier is on the way to collect the return shipment from the customer.	Pre-shipping
shipped	The shipment has been handed over to the carrier and is now in transit.	Post-shipping
in_transit	The shipment has been collected, processed, and is en route to the destination.	Post-shipping
out_for_delivery	The shipment is in the final delivery phase and is on its way to the customer.	Post-shipping
awaiting_customer_collection	The shipment is ready for collection by the customer at a collection point. Applicable for collection orders.	Post-shipping
delivered	The shipment has been successfully delivered to the recipient. Final status.	Post-shipping
suspended	Delivery has been suspended due to issues such as an invalid address or customs clearance problems.	Post-shipping
delayed	Delivery of the shipment is delayed due to operational reasons.	Post-shipping
missing	The shipment has been lost or misplaced by the carrier.	Post-shipping
failed_delivery_attempt	The carrier attempted but failed to deliver the shipment. A reattempt may occur depending on carrier policy.	Post-shipping
ready_for_return	After failed delivery attempts, the shipment is now being processed for return to the sender.	Post-shipping
return_in_transit	The shipment is on its way back to the sender after failed delivery attempts.	Post-shipping
returned	The shipment has been successfully returned to the sender. Final status.	Post-shipping
delivery_confirmed	(Optional final state) The shipment has been delivered and confirmed by the recipient.	Post-shipping
return_confirmed	(Optional final state) The shipment has been returned and confirmed by the origin location.	Post-shipping