Orders

An order on Palamond is a RequestGroup envelope wrapping one or more child requests: MedicationRequest for prescriptions, ServiceRequest for labs. The group is the order; the children are its line items. You read orders from the record plane; the patient's decisions go through one endpoint.

The order model

The intent field is the state machine. Both the group and its children start as proposal and flip to order when the order is placed.

import type { RequestGroup } from '@palamond/sdk/fhir';

const proposals: RequestGroup[] = await palamond.searchResources('RequestGroup', {
  status: 'active',
  intent: 'proposal',
});
const group = proposals[0];

const items = await Promise.all(
  (group.action ?? []).map((a) => palamond.readReference(a.resource!)),
);

Direct orders versus proposals

A provider can place a direct order, in which case the destination and fulfillment are authored up front and the intent is order immediately. More often the provider builds an order proposal: the group and children are intent=proposal, and fulfillment is deliberately left unset because the patient will choose it.

Deciding a proposed order

The patient decides per line item with one call: orders.decide, which takes the proposal RequestGroup and the decisions and returns the completed decision Task. Each decision is accept or decline; accepted items carry the fulfillment method that fits their kind:

• medication: mail-order or retail-pickup
• lab: home-kit or in-person-draw

const task = await palamond.orders.decide(group.id, [
  {
    item: `MedicationRequest/${items[0].id}`,
    decision: 'accept',
    method: 'mail-order',
    performer: 'Preferred Pharmacy',
  },
  {
    item: `ServiceRequest/${items[1].id}`,
    decision: 'decline',
  },
]);

Deciding is one-way: a second call for the same order answers 409 conflict. The full walkthrough is in Decide an Order.

Proposal to order promotion

Recording the decisions is the signal. The platform reads them and does the writes your app must not:

• accepted children get the chosen fulfillment stamped on them and flip intent to order,
• declined children are revoked,
• the group flips to order when anything was accepted, or is revoked when everything was declined.

Confirm the result on the record plane:

const placed = await palamond.searchResources('MedicationRequest', {
  intent: 'order',
  _sort: '-authoredon',
});

Patient-originated requests

A patient can also propose: a medication they want considered, a protocol from the catalog, or a treatment-option preference. requests.create records the proposal and opens the clinician review.

const { request, reviewTask } = await palamond.requests.create({
  kind: 'medication',
  medication: 'Tretinoin 0.05% cream',
  note: 'Used this before with good results.',
});

The platform forces the safe fields (intent: 'proposal', the patient as requester), and a clinician authorizes or declines. That is the mirror image of the flow above: here the patient proposes and the provider decides, rather than the provider proposing and the patient choosing fulfillment. Track progress by reading the returned request on the record plane.