Will-call and refills

Queue finished orders for pickup, search generics, and schedule refill reminders.

You close the loop between dispensing and the patient walking out with their medicines. Park finished work in the will-call queue, find substitutes with generic search, and schedule refills before patients run out. Everything here lives in apps/server/src/features/dispensing/route.ts.

Enqueue a finished order for pickup

You park a dispensed prescription or completed sale with POST /dispensing/will-call. Only patient_name is required; link the source order when you have it.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"patient_name":"Jane Doe","patient_phone":"+256700000000","prescription_id":"<rx-id>"}' \
  "$API/dispensing/will-call"

New entries start in ready status with signature_captured set to 0. You can pass prescription_id, sale_id, or both, and the branch_id defaults to your own branch when you omit it. The queue lives in the will_call table in packages/database/schema.sql, so there is no migration for you to run.

List the ready queue and record pickup

You pull the pickup queue with GET /dispensing/will-call, which defaults to status=ready and paginates twenty per page. Hand the medicines over, then close the entry with the pickup endpoint.

curl -H "Authorization: Bearer $TOKEN" \
  "$API/dispensing/will-call?status=ready&page=1"

curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signature_captured":true}' \
  "$API/dispensing/will-call/<will-call-id>/pickup"

Pickup flips the status to picked_up, stamps picked_up_at, and records whether you captured a signature, as written by pickupWillCall in apps/server/src/features/dispensing/service.ts. Pass signature_captured: true from your register screen when the patient signs, since the default is unsigned. Filter status=picked_up later when you audit handoffs; the list query accepts ready, picked_up, returned_to_stock, or cancelled.

Find substitutes with generic search

You search by brand or generic name with GET /dispensing/generic-search. Your term must be at least two characters, and you get the top 25 active, non-deleted matches.

curl -H "Authorization: Bearer $TOKEN" \
  "$API/dispensing/generic-search?q=amox"

Results return id, name, generic_name, strength, form, selling_price, and stock_quantity, ordered by stock descending over all branches, as assembled in apps/server/src/features/dispensing/queries.ts. Use this at the counter when the prescribed brand is out and you need an equivalent to offer.

Schedule and review refill reminders

You create a reminder with POST /dispensing/refills by sending medicine_id and due_date. The channel defaults to sms and the status starts as pending.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"medicine_id":"<id>","due_date":"2026-10-27","channel":"sms","notes":"Call if no response"}' \
  "$API/dispensing/refills"

You work the follow-up list with GET /dispensing/refills, which returns up to 50 pending reminders for your branch ordered by nearest due date with the medicine name joined in. The reminders live in the refill_reminders table in packages/database/schema.sql, and listRefills in apps/server/src/features/dispensing/queries.ts reads only the pending ones, so a sent or cancelled reminder drops out of the queue on its own. Process this list daily so chronic patients never gap their doses.

Attach a reminder to a customer

You link a refill to a customer record with the optional customer_id field at creation time so your follow-up call has the right phone number and history. Leave it empty for walk-in patients you track by medicine and due date alone.

Branch scoping applies here too: you only see reminders for your own branch, and branch_id on create defaults to yours. Pair this list with the customer credit view in Customers and credit when you call patients with outstanding balances.

Next steps

Revisit the dispense step that feeds this queue in Prescriptions, and confirm controlled handoffs in Controlled drugs.