Order lifecycle

PublicOrderStatus has exactly four values:

Status	Meaning	What triggers it
processing	Paid, not yet at a partner-visible checkpoint.	Set at order creation. Also covers internal trouble (a stuck or retrying Quest placement) — that operational detail never surfaces to partners; contact support if an order sits here unexpectedly long.
requisition_ready	The lab requisition PDF is available.	The order is placed at Quest and a requisition is issued.
results_ready	Structured results and result PDFs are available.	Quest results are delivered electronically from the lab, or uploaded by a JustLabs operator.
cancelled	Cancelled; refunded (or refund pending).	A successful DELETE /orders/{id}.

Poll GET /orders/{id} or GET /orders?status=... to track status, or subscribe to webhooks (§7) to avoid polling.

Pagination with ?status=: always paginate until nextCursor comes back null — do not stop as soon as data is empty. Filtering by status is applied after the underlying page is fetched, so an intermediate page can legitimately return data: [] with a non-null nextCursor (none of the rows in that window matched the filter, but more unfiltered rows exist further back). Treat nextCursor === null as the only reliable end-of-list signal.

Cancelling an order

curl -X DELETE https://labify-staging-3hnx3fg7ca-uc.a.run.app/api/v1/orders/order_123 \
  -H "Authorization: Bearer $JUSTLABS_API_KEY"

The cancel window is 60 minutes from order creation. JustLabs holds a newly-created order for an hour before placing it at Quest specifically so it can be cancelled — Quest has no cancellation API, so once an order is placed it cannot be undone by JustLabs or the partner. After that hour (or sooner, if placement happens early), cancellation fails with 409 cannot_cancel.

details.reason on that 409 tells you why:

reason	Meaning
already_cancelled	Already cancelled — nothing to do.
requisition_issued	The order is already at Quest (requisition issued).
may_exist_at_quest	Placement outcome is unconfirmed; JustLabs support is verifying directly with Quest.
placing	Placement is happening right now.
placed	Already placed at Quest.
fullscript_draft_exists	A JustLabs operator is manually preparing this order for placement — contact support@justlabs.health.
not_cancellable	Not in a cancellable state for another reason — contact support@justlabs.health.

A successful cancellation returns the order with refund: "issued" (the Stripe refund succeeded inline) or refund: "pending" (cancellation succeeded, but JustLabs staff were alerted to issue the refund by hand — this is rare and does not require any action from you).

---