Medication Orders Payload Structure

Quick summary

The Medication orders payload structure includes multiple fields under the orders object. Understand the available fields that you receive in the Medication orders payload to parse and save orders to your EHR.

Last updated:June 2026

The Headed Web SDK returns Medication orders when a provider submits a note. The note submission payload includes medication_orders under orders, along with noteId, encounterId, and contents. This guide describes the Medication orders payload structure and explains each field in a Medication order object.

Refer to Medication orders overview for instructions to enable Medication orders in your Web SDK integration.

Medication orders payload

When you submit a note, the Headed Web SDK returns a note submission payload after it successfully submits the note. The payload includes noteId, encounterId, and contents. If you enable Medication orders, the payload also includes the orders object. Medication details are available in orders.medication_orders. You can receive the payload using either of the following methods:

onNoteSubmit prop (React only, recommended)
note-submission:success event (React and JavaScript)

Refer to Receiving note content in Note management for how to handle note sections and the full response structure. Example schema:

JSON

{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "encounterId": "encounter-12345",
  "contents": [],
  "orders": {
    "medication_orders": {
      "values": [],
      "partial_values": []
    }
  }
}

The note submission payload includes the orders object when you enable Medication orders in your Web SDK integration.

To enable Medication orders, pass the Medications LOINC code 52471-0 in ambientOptions.sections. Refer to Medication orders overview for instructions to enable Medication orders in your Web SDK integration.

orders

object

Structured orders returned on note submission. For Medication orders, read orders.medication_orders with values and partial_values.

For noteId, encounterId, and contents, refer to Response fields in Note management.

Medication order payload structure

The example below shows the payload structure for a single Medication order object.

JSON

{
  "drug_name": "Lisinopril",
  "medication_code": {
    "type": "RXCUI",
    "code": "314076"
  },
  "dosage": {
    "raw_value": "1 tablet",
    "quantity": 1,
    "unit": "TAB"
  },
  "frequency": {
    "raw_value": "Once daily",
    "structured_value": "ONE_A_DAY"
  },
  "instructions": "Take one tablet by mouth once daily",
  "medication_timing": {
    "raw_value": "In the morning",
    "structured_value": "IN_THE_MORNING"
  },
  "strength": {
    "raw_value": "10mg"
  },
  "format": {
    "raw_value": "Tablet"
  },
  "route": {
    "raw_value": "By mouth"
  },
  "linked_diagnosis_codes": [
    {
      "type": "ICD10",
      "code": "I10"
    }
  ],
  "number_of_refills": 3,
  "start_date": "2024-01-15T00:00:00Z",
  "end_date": "2024-04-15T00:00:00Z",
  "duration_in_days": 90,
  "status": "REFILLED",
  "metadata": {
    "origin": "EMR",
    "encounter_relation": "CURRENT_ENCOUNTER"
  }
}

Available fields

Each field in a Medication order object can have the following values. Use these fields to parse the Medication orders payload and save orders to your EHR.

Hide Medication order fields

drug_name

string

required

Full medication name (for example Lisinopril). This field is required when Medication orders are enabled in your Web SDK integration.

medication_code

object

Standardized medication identifier.

type: Coding system (for example RxCUI). If this is present, you cannot edit the medication value in the Web SDK UI.
code: Code value.

dosage

object

Amount per administration.

raw_value: Human-readable dosage string. For example 1 tablet.
quantity: Numeric quantity when structured. For example 1.
unit: Unit code (for example TAB).

frequency

object

Administration frequency.

raw_value: Human-readable frequency.
structured_value: Structured value (for example ONE_A_DAY).

instructions

string

Free-form sig or patient instructions.

medication_timing

object

Timing modifiers.

raw_value: Human-readable timing. For example In the morning.
structured_value: Structured value. For example IN_THE_MORNING.

strength

object

Medication strength. Includes raw_value. For example 10mg.

format

object

Dosage form. Includes raw_value. For example Tablet.

route

object

Route of administration. Includes raw_value (for example By mouth).

linked_diagnosis_codes

array

Diagnoses linked to the order. Each entry includes type (for example ICD10) and code.

number_of_refills

integer

Number of refills when specified.

start_date

string

Start date-time in RFC3339 format. For example 2026-01-01T00:00:00Z.

end_date

string

End date-time in RFC3339 format.

duration_in_days

integer

Duration in days when specified.

status

string

Order status: ACTIVE, DISCONTINUED, or REFILLED.

metadata

object

Provenance for the order.

origin: EMR or SUKI_AMBIENT.
encounter_relation: CURRENT_ENCOUNTER or PRIOR_ENCOUNTER when origin is EMR.

When origin is EMR, the encounter_relation field is required.

Example code

The example code below shows how to parse the Medication orders payload and save orders to your EHR.

Best practices

Check for orders before you parse it. The object is returned only when Medication orders are enabled.
Treat values as ready for EHR workflows. Send partial_values for manual review or completion.
Store noteId and encounterId with each order batch for tracking and reconciliation.
Validate required fields before you submit orders to the EHR.
Log the full submission payload to help troubleshoot ingestion issues.
Do not assume the Web SDK submits orders. Your application must validate and write orders to the EHR.
Handle ORD_SDK_* errors during order generation and validation.

Next steps

Refer to Medication orders overview to enable Medication orders in your Web SDK integration. Refer to Medication orders error codes to handle errors during medication order generation.

​Medication orders payload

​Medication order payload structure

​Available fields

​Example code

​Best practices

​Next steps

Medication orders payload

Medication order payload structure

Available fields

Example code

Best practices

Next steps