Renewing Medication Requests

For product owners and partners: use this page to understand how patients can request a renewal of an existing medication prescription through the MediKIT API, and what happens to that request afterwards.

For architects and developers: use this page to implement the $renew operation with the correct Parameters request shape and response handling, for both a single medication request and a batch of them.

Medication request renewal is a FHIR R4 custom operation. Each request creates a new MedicationRequest, scoped to a single patient and organization, referencing the original request it renews.

What this endpoint is for

Use $renew when your product needs to let a patient request a renewal of an existing medication prescription, for example from a patient portal's medication overview.

A renewal always enters practitioner review before it becomes active. It is never activated automatically.

Endpoint map

Use case	Endpoint	Notes
Search medication requests	`GET /v2/{organizationId}/fhir/R4/Patient/{patientId}/MedicationRequest`	Supports `status`, `code`, `period-of-use-start`
Read medication request by ID	`GET /v2/{organizationId}/fhir/R4/Patient/{patientId}/MedicationRequest/{id}`	Returns one stored medication request
Renew one medication request	`POST /v2/{organizationId}/fhir/R4/Patient/{patientId}/MedicationRequest/{id}/$renew`	Body is a `Parameters` resource
Renew multiple medication requests	`POST /v2/{organizationId}/fhir/R4/Patient/{patientId}/MedicationRequest/$renew`	Body is a `Parameters` resource listing the requests to renew

Required access

Required scopes

medication-request.read: search and read
medication-request.renew: the $renew operation

Searching for medication requests

GET .../MedicationRequest supports the following query parameters:

Parameter	Description
`status`	The status of the medication requests to list.
`code`	The prescribed medicine's code to filter by. Valid systems are HPK, GPK, PRK, and ATC.
`period-of-use-start`	The start of the period of use, e.g. `period-of-use-start=ge2025-01-01` lists all requests whose period of use started on or after January 1st, 2025.
`_count`	Maximum number of medication requests per page.
`page`	Pagination cursor. Follow the `next` link on a returned `Bundle` rather than setting this yourself.

Which requests are eligible for renewal

The prescribed medicine is returned as an inline medicationCodeableConcept, carrying the medication's own codes (for example its ATC and G-Standaard codings) and display text, so no separate lookup is needed to know what was prescribed.

A MedicationRequest returned by search or read carries an additional meta.tag entry when it is currently eligible for renewal, with system https://medikit.nl/fhir/CodeSystem/medikit-patient-portal-functionality and code repeatable-by-patient. This tag is descriptive only: it cannot be used as a search filter.

A request is eligible for renewal when it meets all of the following:

the medicine it prescribes can be identified, whether named by reference or carried as an inline concept
that medicine has an ATC code, and that code is not on the organization's restricted list (e.g. certain opioids and benzodiazepines)
its status is active or completed
it has a defined period of use with both a start and end date, and that period started within the last 365 days
it has at least one dosage instruction
it has a pharmacy assigned, either on the request itself or as the patient's preferred pharmacy
it has an initial fill defined

Renewing a medication request

To renew a request, first identify the existing MedicationRequest (or requests) to renew, then POST a Parameters resource to the appropriate $renew endpoint.

Parameter	Required	Repeatable	Description
`start-date`	Yes	No	A full `date` (`YYYY-MM-DD`): the start of the new request's period of use. The new period's duration is derived automatically from the original request's period of use.
`medication-request`	Yes, when renewing multiple requests	Yes	A `Reference` to a `MedicationRequest` to renew, e.g. `MedicationRequest/abc123`. Not used when renewing a single request: the request to renew is already identified by the endpoint path in that case.

Renewing a single request

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "start-date",
      "valueDate": "2025-02-01"
    }
  ]
}

POST this to MedicationRequest/{id}/$renew, where {id} identifies the request to renew.

Renewing multiple requests

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "start-date",
      "valueDate": "2025-02-01"
    },
    {
      "name": "medication-request",
      "valueReference": {
        "reference": "MedicationRequest/abc123"
      }
    },
    {
      "name": "medication-request",
      "valueReference": {
        "reference": "MedicationRequest/def456"
      }
    }
  ]
}

POST this to MedicationRequest/$renew.

Response shape

Renewing a single request returns the newly created MedicationRequest directly. Renewing multiple requests returns a FHIR R4 Bundle (type: collection) containing one newly created MedicationRequest per renewed request.

Each newly created request has:

status: draft
basedOn referencing the original request

A renewal request remains in draft until a practitioner reviews it.

Error behavior

Status	Scenario
`403`	Client lacks the required scope, or access to the requested patient context
`404`	A referenced medication request could not be found
`422`	Missing/unrecognized parameters, invalid `start-date`, or a referenced medication request does not meet the eligibility requirements above
`500`	The request was valid but could not be persisted
`503`	The store was unavailable. The same request may succeed if retried

What this endpoint is for​

Endpoint map​

Required access​

Required scopes​

Searching for medication requests​

Which requests are eligible for renewal​

Renewing a medication request​

Renewing a single request​

Renewing multiple requests​

Response shape​

Error behavior​

Related pages​