---
title: Will-call and refills
description: 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.

```bash
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.

```bash
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.

```bash
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`.

```bash
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](/operations/customers-and-credit) when you call patients with outstanding balances.

### Next steps

Revisit the dispense step that feeds this queue in [Prescriptions](/dispensing/prescriptions), and confirm controlled handoffs in [Controlled drugs](/dispensing/controlled-drugs).