Prescription Orchestrator API

7-step prescription approval pipeline coordinating physician registry, pharmacy router, payment, shipping, and notifications.

Overview

The Prescription Orchestrator coordinates the full prescription approval workflow across 5 downstream services. When a prescriber approves (or denies) a prescription via the RxQueue admin portal, the orchestrator runs a deterministic 7-step pipeline that resolves medication config, looks up the patient in Canvas FHIR, selects the correct prescriber, submits to a pharmacy, charges payment, creates a shipment label, and sends patient notifications.

Instead of the RxQueue UI calling each service directly, it makes a single POST /orchestrator/approve call and the orchestrator handles all downstream coordination, failure handling, and audit logging.

Base URL

https://api.yourera.com/orchestrator

How It Works

1. Prescriber approves a task in the RxQueue admin portal
2. Admin portal calls POST /orchestrator/approve with taskId, medication, and canvasPatientId
3. Orchestrator runs the 7-step pipeline (see Pipeline Steps)
4. Each step calls a downstream service via HMAC-authenticated HTTP clients
5. Every run (success or failure) is persisted to the orchestration_runs table
6. The synchronous response includes completed steps, warnings, and any errors

Authentication

All /orchestrator/* endpoints require HMAC-SHA256 authentication. Each API client is issued an API key (public identifier) and an API secret (used for signing). Keys are stored in the orchestrator_api_keys table.

Required Headers

Signature Formula

The signing string is the timestamp, a dot, and the JSON-stringified request body:

HMAC-SHA256(apiSecret, timestamp + '.' + JSON.stringify(body))

The result is encoded as a lowercase hex string.

Node.js Example

import crypto from 'node:crypto';

const API_KEY = 'your-api-key';
const API_SECRET = 'your-api-secret';
const BASE_URL = 'https://api.yourera.com/orchestrator';

function signRequest(body) {
  const timestamp = new Date().toISOString();
  const bodyStr = JSON.stringify(body);
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(timestamp + '.' + bodyStr)
    .digest('hex');

  return { timestamp, signature };
}

// Approve a prescription
const body = {
  taskId: 'task-abc123',
  medication: 'semaglutide',
  canvasPatientId: 'patient-uuid-here',
  dosage: '0.25mg weekly',
};
const { timestamp, signature } = signRequest(body);

const response = await fetch(`${BASE_URL}/approve`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: JSON.stringify(body),
});

Approve Prescription

Request Body: ApproveRequest

Example Request

{
  "taskId": "task-abc123",
  "medication": "semaglutide",
  "canvasPatientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "dosage": "0.25mg weekly"
}

Response

Success (200)

{
  "success": true,
  "result": {
    "success": true,
    "completedSteps": [
      "medication_config",
      "patient_details",
      "prescriber_resolution",
      "pharmacy_submission",
      "payment",
      "shipment",
      "notification"
    ],
    "warnings": [],
    "medication": "Semaglutide 5mg/mL",
    "patientName": "Jane Smith",
    "state": "TX",
    "submissionId": "sub-uuid-from-pharmacy-router"
  }
}

Success with Warnings (200)

Non-blocking steps (payment, shipment, notification) can fail without failing the pipeline. Failures appear in the warnings array:

{
  "success": true,
  "result": {
    "success": true,
    "completedSteps": ["medication_config", "patient_details", "prescriber_resolution", "pharmacy_submission", "payment", "shipment", "notification"],
    "warnings": ["payment_failed", "notification_failed"],
    "medication": "Semaglutide 5mg/mL",
    "patientName": "Jane Smith",
    "state": "TX",
    "submissionId": "sub-uuid-from-pharmacy-router"
  }
}

Pipeline Failure (500)

When a blocking step fails, the pipeline halts and the response includes which step failed:

{
  "error": "Pharmacy submission failed",
  "failedStep": "pharmacy_submission",
  "result": {
    "success": false,
    "completedSteps": ["medication_config", "patient_details", "prescriber_resolution"],
    "failedStep": "pharmacy_submission",
    "error": "Pharmacy submission failed",
    "warnings": [],
    "medication": "Semaglutide 5mg/mL",
    "patientName": "Jane Smith",
    "state": "TX"
  }
}

Error Responses

Deny Prescription

Request Body: DenyRequest

Example Request

{
  "taskId": "task-def456",
  "reason": "BMI does not meet clinical criteria for GLP-1 therapy",
  "canvasPatientId": "patient-uuid-abc123"
}

Response

Success (200)

{
  "success": true,
  "taskId": "task-def456",
  "denied": true
}

Error Responses

Refill Check

Request Body

No request body required. The endpoint queries due schedules from the database internally.

// Empty body or omit body entirely
{}

Response

Success (200)

{
  "processed": 3,
  "results": [
    {
      "scheduleId": "sched-uuid-1",
      "canvasPatientId": "patient-uuid-1",
      "medication": "semaglutide",
      "processed": true
    },
    {
      "scheduleId": "sched-uuid-2",
      "canvasPatientId": "patient-uuid-2",
      "medication": "tirzepatide",
      "processed": true
    },
    {
      "scheduleId": "sched-uuid-3",
      "canvasPatientId": "patient-uuid-3",
      "medication": "semaglutide",
      "processed": false,
      "reason": "max_refills_reached"
    }
  ]
}

Refill Decision Reasons

Each schedule is evaluated by shouldProcessRefill(). Skipped schedules include one of these reasons:

Error Responses

Get Status

Path Parameters

Example Request

GET /orchestrator/status/task-abc123

Response

Success (200)

{
  "taskId": "task-abc123",
  "runs": [
    {
      "id": "run-uuid-1",
      "taskId": "task-abc123",
      "medication": "semaglutide",
      "canvasPatientId": "patient-uuid",
      "status": "completed",
      "completedSteps": ["medication_config", "patient_details", "prescriber_resolution", "pharmacy_submission", "payment", "shipment", "notification"],
      "failedStep": null,
      "error": null,
      "warnings": [],
      "result": { /* full PipelineResult */ },
      "createdAt": "2026-03-20T14:30:00.000Z",
      "updatedAt": "2026-03-20T14:30:02.000Z"
    }
  ]
}

Error Responses

Pipeline Steps

The approval pipeline runs 7 steps sequentially. Steps 1–4 are blocking: if any of them fails, the pipeline halts immediately and returns the error. Steps 5–7 are non-blocking: failures are captured as warnings but the pipeline still reports success.

Step 1: Resolve Medication Config

Looks up the medication key ("semaglutide", "tirzepatide", or "nad") in the MEDICATION_CONFIGS map. Returns the display name, sig (prescriber instructions), quantity, unit, refill count, Boothwyn SKU, and concentration warning flag.

Blocking: Yes. An unknown medication key halts the pipeline.

Calls: Local config lookup (no network call).

Step 2: Get Patient Details

Fetches the patient record from Canvas FHIR using the canvasPatientId. Extracts first name, last name, state, email, phone, and full shipping address (line1, city, state, zip). This data feeds into every subsequent step.

Blocking: Yes. If the Canvas FHIR call fails or the patient is not found, the pipeline halts.

Calls: Canvas FHIR API — GET /Patient/:id

Step 3: Resolve Prescriber

Determines which prescriber to assign based on the patient's state. Ali Nolan FNP-C handles 6 states (AK, CT, HI, LA, NM, NY); Neelima Singh MD is the fallback for all other states. Returns the prescriber's name, suffix, NPI, and Canvas practitioner ID.

Blocking: Yes (always succeeds — every state maps to a prescriber).

Calls: Local routing lookup (no network call). See Prescriber Routing.

Step 4: Submit to Pharmacy

Calls the Integration Service Pharmacy Router via its HMAC-authenticated POST /rx/prescriptions/submit endpoint. Passes the patient demographics, prescriber info, medication config, and task ID. The Pharmacy Router determines the target pharmacy (GMP/PioneerRx or Boothwyn) based on the patient's state.

Blocking: Yes. If the pharmacy submission fails, the pipeline halts. Payment MUST NOT be charged without a successful pharmacy submission.

Calls: Pharmacy Router — POST /rx/prescriptions/submit

Step 5: Charge Payment

Charges the patient's saved card via Stripe using a PaymentIntent with off_session = true. The card was saved during intake via a SetupIntent. The charge amount is determined by the medication and any applied discount codes.

Blocking: No. Payment failure is recorded as a "payment_failed" warning but does not halt the pipeline.

Calls: Payment service (Stripe) — chargePayment(canvasPatientId)

Step 6: Create Shipment

Creates a shipping label via the Shipping Service. For GMP (PioneerRx) orders, this generates a FedEx label immediately. For Boothwyn orders, the shipment is created asynchronously: when Boothwyn ships the order, they send a webhook to the Pharmacy Router, which updates the submission and sends an HMAC-signed callback to the orchestrator's POST /api/pharmacy-router/callback endpoint. The callback handler then creates the shipment record and notifies the patient with tracking information.

Blocking: No. Shipment failure is recorded as a "shipment_failed" warning.

Calls: Shipping Service — createShipment(patient, medication, pharmacy)

Receives (async): Pharmacy Router callback — POST /api/pharmacy-router/callback (when Boothwyn ships)

Step 7: Send Notifications

Dispatches a prescription_approved notification to the patient via email and SMS. The notification includes the patient name, medication display name, and pharmacy name.

Blocking: No. Notification failure is recorded as a "notification_failed" warning.

Calls: Notification Service — sendNotification(type, recipient, variables)

Pipeline Failure Modes

Medication Config

The orchestrator maintains a static medication configuration map. Each entry defines the display name, prescriber instructions (sig), dispensing quantity, Boothwyn SKU, and refill count. The medication key passed in the approve request must match one of these entries exactly.

MedicationConfig Interface

interface MedicationConfig {
  displayName: string;
  sig: string;
  quantity: string;
  unit: string;
  refills: number;
  boothwynSku?: string;
  concentrationWarning?: boolean;
}

Prescriber Routing

The orchestrator routes each prescription to one of two prescribers based on the patient's state. getPrescriberForState(state) performs this lookup synchronously.

PrescriberInfo Interface

interface PrescriberInfo {
  firstName: string;
  lastName: string;
  suffix: string;
  npi: string;
  canvasPractitionerId: string;
}

Refill Logic

Refill scheduling determines when a patient's next prescription fill should be processed. The orchestrator uses a date-based formula with a shipping buffer to ensure medication arrives before the patient runs out.

Next Fill Date Formula

nextFillDate = lastFillDate + daysSupply - SHIPPING_BUFFER_DAYS

SHIPPING_BUFFER_DAYS = 3. For a 30-day supply filled on March 1, the next fill date would be March 1 + 30 - 3 = March 28, giving 3 days for shipping before the patient's supply runs out on March 31.

Refill Decision Flow

shouldProcessRefill(schedule, today) evaluates each schedule:

1. If status is "cancelled", "paused", or "completed" → skip
2. If refillsSent >= totalRefillsAllowed → skip (max reached)
3. If nextFillDate > today → skip (not yet due)
4. Otherwise → process the refill

Schedule Update After Successful Refill

When a refill pipeline completes successfully:

1. refillsSent is incremented by 1
2. lastFillDate is set to today
3. nextFillDate is recalculated using the formula above
4. If refillsSent >= totalRefillsAllowed, status is set to "completed"

RefillSchedule Interface

interface RefillSchedule {
  id: string;
  status: 'active' | 'paused' | 'cancelled' | 'completed';
  totalRefillsAllowed: number;
  refillsSent: number;
  daysSupply: number;
  lastFillDate: Date;
  nextFillDate: Date;
}

Inter-Service Call Diagram

The orchestrator sits at the center of the prescription workflow, calling 5 downstream services. All inter-service calls use HMAC-SHA256 authentication.

                        +------------------+
                        |   RxQueue Admin   |
                        |     Portal        |
                        +--------+---------+
                                 |
                          POST /approve
                          POST /deny
                                 |
                        +--------v---------+
                        |   Orchestrator    |
                        +--+--+--+--+--+---+
                           |  |  |  |  |
          +----------------+  |  |  |  +----------------+
          |                   |  |  |                    |
+---------v------+  +---------v--+  |  +----------+  +--v-----------+
|  Canvas FHIR   |  |  Pharmacy  |  |  | Shipping |  | Notification |
|  (Patient API) |  |   Router --+--+  | Service  |  |   Service    |
+----------------+  +--+---------+  |  +----------+  +--------------+
                        |      ^    |
                   submit|     |callback (async)
                        v      |    |
                    +----------+-+  |
                    | Boothwyn /  |  |
                    | Strive API  |  |
                    +-------------+  |
                                    |
                           +--------v-------+
                           |    Stripe       |
                           | (Payment API)   |
                           +----------------+

Service Endpoints Called

Database Schema

The orchestrator uses PostgreSQL (shared RDS instance hisera-db) with Drizzle ORM. All tables use UUID primary keys and timestamptz columns.

orchestration_runs

Audit log of every pipeline execution (approve, deny, or refill).

refill_schedules

Tracks recurring prescription refills for each patient.

payment_holds

Tracks Stripe payment state for each patient.

patient_mappings

Maps Canvas patient IDs to pharmacy-specific patient/case IDs.

sync_logs

Detailed log of individual API calls to downstream services.

medication_configs

Database-backed medication configuration (supplements the in-code MEDICATION_CONFIGS map).

orchestrator_api_keys

HMAC API keys for authenticating callers.

Health Check

Response (200)

{
  "status": "ok",
  "service": "prescription-orchestrator",
  "timestamp": "2026-03-20T14:30:00.000Z"
}