Shipment Lifecycle

Every shipment follows a defined state machine. Understanding the statuses helps you build polling, retries, and exception handling correctly.

Lifecycle overview

draft -> payment_pending -> queued -> printing -> printed -> shipped -> delivered
   |         |
   |         -> payment_failed
   |
   -> cancelled

queued -> cancelled
printed -> cancelled
shipped -> refunded

Status reference

`draft`

Shipment exists and draft quotes are available.

`payment_pending`

Corvo is charging the organization card or retrying payment-related work.

`payment_failed`

Payment or post-payment label purchase failed.

`queued`

Payment succeeded and the shipment is waiting for print routing.

`printing`

Document and label jobs have been submitted to printers.

`print_error`

A print job failed or required metadata was missing.

`printed`

Document and label are printed and waiting for carrier handoff.

`shipped`

Corvo has handed the package to the carrier.

`delivered`

Carrier tracking confirmed delivery.

`cancelled`

Shipment was cancelled before terminal completion.

`refunded`

Shipment was refunded after charge.

Quote expiry

Draft quotes expire at the timestamp returned in quotes_expire_at. Buying with an expired quote returns RATE_EXPIRED with HTTP 410. Create a new draft to get fresh quotes.

Cancellation rules

Customer-facing cancellation is allowed only from draft, queued, and printed. A cancellation does not automatically create a public refund workflow.

Use the event timeline

Shipment detail responses include an ordered events array. That timeline is the best source of truth for explaining status changes back to your users or operators.

Example cancellation call

curl -X POST https://corvo.to/api/v1/shipments/f47ac10b-58cc-4372-a567-0e02b2c3d479/cancel \
  -H "Authorization: Bearer $CORVO_API_KEY"