Documentation / Orders and fulfilment

Orders and fulfilment

The order lifecycle, the durable queue, tracking, refunds and cancellations.

Order handling is the part of the platform that has to work while you are asleep, so it is built as a queue with explicit states rather than as work done inside the checkout request.

The lifecycle

Status	Meaning
pending	Created, payment not yet confirmed.
paid	Payment captured. Eligible for supplier submission.
queued	A submission job exists and is waiting for its turn or its retry.
submitted	Accepted by the supplier, awaiting shipment.
shipped	Tracking received and pushed to the customer.
delivered	Carrier reported delivery.
cancelled	Cancelled before shipment, refunded if payment was captured.
refunded	Refunded after shipment.
failed	Exhausted submission attempts. Requires an operator decision.

Why submission is queued

Submitting to a supplier inside the checkout request means a slow supplier makes checkout slow and a broken supplier makes checkout fail. Instead, payment confirmation enqueues a job. The job carries attempt count, max attempts, a run-at time and a worker lease.

• A worker claims a job with a conditional update on the lease columns, so two workers can never run the same job.
• A worker that dies mid-job has its lease expire and the job is retried, rather than wedging the queue.
• A job that exhausts its attempts becomes failed and surfaces on the order-queue screen instead of disappearing.

Tracking

Tracking numbers arrive by supplier webhook where the supplier supports it and by scheduled poll where it does not. Either way the customer notification is sent once — sends are deduplicated on the order and event type.

Refunds and cancellations

A cancellation before shipment cancels supplier-side first, then refunds. A refund after shipment refunds without cancelling, because the goods are already moving. Both write to the audit log with the acting user.

Re-running

A failed order can be re-run from the order-queue screen. Re-running creates a fresh job rather than resurrecting the dead one, so the failure history stays readable.

Something wrong or missing on this page? Tell us — documentation corrections are treated as bugs.