RxRenewal Message

Overview

RxRenewal is a type of message sent by pharmacy to subscriber when the medication should be renewed. It is required that RxRenewal is preceded by NewRx.

Receiving RxRenewalRequest

Once the pharmacy sends an RxRenewalRequest, ePrescription module receives Surescripts message at /eprescriptions/rx endpoint and saves it to Aidbox. Resources created:

• MedicationRequest reflecting the incoming data
• DetectedIssue - if only there were some mismatches in related resources
• Provenance - solely as a record that an event has occurred. It is intended to serve as an audit/logging artifact, and should not be relied upon for driving business logic.

There are several ways to track the newly created MedicationRequests:

• Either of Aidbox Subscriptions mechanisms
• Manual/automated tracking based on MedicationRequest modification date and/or status

The ePrescription module creates a DetectedIssue whenever inbound RxRenewal data diverges from existing records; see Detected Issues for the full list of checks and a sample payload.

Renewal statuses

The status of the request is stored in the created MedicationRequest's extension field under http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-status extension. There's also http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-status-reason with a human-readable description of a status.

GET /fhir/MedicationRequest

resourceType: Bundle
type: searchset
meta:
  versionId: '0'
total: ...
link:
  - relation: first
    url: http://127.0.0.1:8789/fhir/MedicationRequest?page=1
  - relation: self
    url: http://127.0.0.1:8789/fhir/MedicationRequest?page=1
entry:
    ...
      - resource:
      ...
      resourceType: MedicationRequest
      extension:
        - url: >-
            http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-status
          valueCode: active
      ...

The initial status is active. For the rest, consult NewRx status table

Responding to RxRenewalRequest

Setting a decision

Available decisions are approved, approved-with-changes, denied, pending or replace. It is represented as an extension:

extension:
  - url: >-
      http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-decision
    valueCode: denied

Denied

denied is the decision that requires the least amount of steps. Setting it in the extension is the only requirement. You can set the denial reason (free text) in decision note extension ( http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-decision-note), but this is optional. Call the /eprescription/rx/respond-to-renewal endpoint to commit your decision:

POST /eprescription/rx/respond-to-renewal

{
  "medicationRequestId": "your-medication-request-id"
}

Pending

Before committing the pending decision you need to

1. 1.
   Set the decision itself:

extension:
  - url: >-
      http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-decision
    valueCode: pending

1. 1.
   Set the expected pended response date:

extension:
  - url: >-
      http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-expected-pended-response-date
    valueDate: '2025-12-12'

1. 1.
   Set the decision note (contrarily to denied decision, it's required for pending):

extension:
  - url: >-
      http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-decision-note
    valueString: Provider is on vacation

1. 1.
   Set the reason code:

;; TODO

Available reason codes are listed in the table below:

Approved

approved decision assumes that only minor changes were made. While the e-prescriptions module could prefill fields like MedicationRequest.dispenseRequest and dosageInstruction, the general approach is to let the prescriber do that.

1. 1.
   Set the decision:

extension:
  - url: >-
      http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-decision
    valueCode: approved

1. 1.

   If during the process of handling incoming renewal request there was a DetectedIssue created (meaning there were mismatches between incoming and existing data), make sure you have resolved the references to implicated contained resources:

   • Patient - MedicationRequest.subject
   • PractitionerRole - MedicationRequest.performer
   • Practitioner - PractitionerRole.practitioner
   • Location - PractitionerRole.location or PractitionerRole.organization
   • Pharmacy - MedicationRequest.requester
   • Medication - for medications contained resource is supported, so it's up to you whether to resolve it or leave as is - MedicationRequest.medication
2. 2.

   Set MedicationRequest.dispenseRequest and MedicationRequest.dosageInstruction. Typically, they are the same as in the request for NewRx: Make sure you set

   • MedicationRequest.dispenseRequest.performer (the pharmacy of initial renewal request)
   • MedicationRequest.dispenseRequest.numberOfRepeatsAllowed - for approved decision it should be the same as pharmacy requested

dispenseRequest:
  quantity:
    code: C48542
    unit: Tablet
    value: 60
    system: urn:app:aidbox:e-prescriptions:ncpdp:QuantityUnitOfMeasure
  performer:
    reference: Organization/my-pharmacy
  expectedSupplyDuration:
    code: d
    unit: days
    value: 30
    system: http://unitsofmeasure.org
  numberOfRepeatsAllowed: 1
dosageInstruction:
  - text: TAKE ONE TABLET TWO TIMES A DAY UNTIL GONE

ApprovedWithChanges

TODO

HTTP response with status 202 designates that the response was successfully transitioned to Surescripts. Surescripts response is reflected in extensions for status and status reason:

• http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-status
• http://aidbox.app/ePrescription/FHIRSchema/medication-request-rx-renewal-status-reason