Dashboard ↗Get an API key
API

Orders API

List, fetch, resolve, approve, submit, reroute, and reconcile fulfillment orders.

The orders API drives an order from intake to a submitted, shipped prescription. Every mutation takes an Idempotency-Key so retries never double-ship, and order objects carry PHI — treat them per the PHI boundary. For the lifecycle these endpoints move an order through, read Orders.

All paths are relative to https://api.neolife.health/v1. All requests take Authorization: Bearer nk_live_… (or nk_sandbox_…).

List orders#

GET /orders

The tenant's orders, newest first, cursor-paginated. Order objects carry PHI.

Query param Description
status Filter to a single lifecycle status.
limit Page size, 1–100 (default 100).
starting_after Cursor — an order id to page after. 
curl "https://api.neolife.health/v1/orders?status=submitted&limit=25" \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

To page, take the id of the last order in a page and pass it as starting_after on the next request.

Get an order#

GET /orders/:id

Fetch a single order with its patient, prescriptions, shipment, and timeline. Returns 404 if no such order exists on your tenant. Carries PHI.

curl https://api.neolife.health/v1/orders/ord_123 \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Plan routing#

POST /orders/routing/plan

Preview where a cart of products would route across your connected pharmacies, per the tenant's routing policy — without creating an order. Useful before you build a checkout or to show a fulfillment estimate. See Routing.

Body field Description
items[].productId A catalog product id to route.
items[].manualConnectionId Optional — pin this line to a specific pharmacy connection instead of letting policy decide. 
curl -X POST https://api.neolife.health/v1/orders/routing/plan \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "productId": "prod_abc" },
      { "productId": "prod_xyz", "manualConnectionId": "conn_empower" }
    ]
  }'

This is a read-only preview and takes no Idempotency-Key.

Resolve an order#

POST /orders/:id/resolve

Clear the flagged ("amber") fields on an order's confirm card: pick the patient and confirm any flagged fields, so the order is ready for provider approval.

Body field Description
patientId The patient this order belongs to.
confirmAmber true to confirm the flagged fields. 
curl -X POST https://api.neolife.health/v1/orders/ord_123/resolve \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1b0c2a-9d6e-4a51-8b2f-1c7e5a9d0e42" \
  -d '{ "patientId": "pat_456", "confirmAmber": true }'

Approve an order#

POST /orders/:id/approve

The clinical gate. Only a licensed provider can approve an order, and on approval the order auto-submits to the pharmacy. A caller who is not an authorized provider gets 403. This is the single call that turns a prepared order into a real, shipping prescription.

curl -X POST https://api.neolife.health/v1/orders/ord_123/approve \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Idempotency-Key: 7c2d1e0a-4b6f-4a51-9d3e-2a8c5f9b0e13"

Returns the approved (and submitted) order.

A provider approval is required for every clinical order. No API key, agent, or staff account can substitute for it — the rest of the API refuses to submit anything that has not been provider-approved.

Submit an order#

POST /orders/:id/submit

Submit an already-provider-approved order to the pharmacy. Most integrations never call this directly — approve auto-submits — but it exists so staff or an agent can (re)trigger submission, for example after a reroute. The endpoint refuses any order that has not been provider-approved.

curl -X POST https://api.neolife.health/v1/orders/ord_123/submit \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Idempotency-Key: 3f1b0c2a-9d6e-4a51-8b2f-1c7e5a9d0e42"

Submission is single-dispatch and domain-idempotent: a retry with the same key — after a crash or timeout — will not produce a second physical shipment. Always send an Idempotency-Key.

Reroute an order#

POST /orders/:id/reroute

Failover for a rejected or failed order: point it at an alternate pharmacy so it can resubmit.

Body field Description
connectionId Optional — the pharmacy connection to reroute to. Omit to let routing policy pick the next-best pharmacy. 
curl -X POST https://api.neolife.health/v1/orders/ord_123/reroute \
  -H "Authorization: Bearer $NEOLIFE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-4a51-8b2f-1c7e5a9d0e42" \
  -d '{ "connectionId": "conn_backup" }'

The response reports whether a target was found:

{
  "rerouted": true,
  "connectionId": "conn_backup"
}

After a successful reroute, submit the order to dispatch it to the new pharmacy.

Reconciliation#

GET /orders/reconciliation

A proof that no fulfillment event was dropped: it reports orphaned webhook counts for your tenant, which should be 0. Poll it to assure yourself that inbound pharmacy status updates are fully accounted for.

curl https://api.neolife.health/v1/orders/reconciliation \
  -H "Authorization: Bearer $NEOLIFE_API_KEY"

Related#

  • Orders — the full order lifecycle and each status.
  • Idempotency — why every mutation takes a key.
  • API reference — base URL, versioning, errors, and rate limits.