> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Medication Orders Payload Structure

> Learn about the Medication orders JSON payload structure returned on Web SDK note submission

<div className="quick-summary-wrapper">
  <div className="quick-summary-header">
    <span className="quick-summary-icon" aria-hidden="true" />

    <span className="quick-summary-title">Quick summary</span>
  </div>

  <div className="quick-summary-content">
    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.
  </div>

  <div className="quick-summary-footer">
    <span className="quick-summary-footer-icon" aria-hidden="true" />

    <span className="quick-summary-footer-text">Last updated:</span>
    <span className="quick-summary-footer-date">June 2026</span>
  </div>
</div>

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.

<Note>
  Refer to [Medication orders overview](/web-sdk/medication-orders/overview) for instructions to enable Medication orders in your Web SDK integration.
</Note>

## 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](/web-sdk/guides/note-management#receiving-note-content) in Note management for how to handle note sections and the full response structure.

**Example schema:**

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "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.

<Note>
  To enable Medication orders, pass the Medications LOINC code `52471-0` in `ambientOptions.sections`. Refer to [Medication orders overview](/web-sdk/medication-orders/overview) for instructions to enable Medication orders in your Web SDK integration.
</Note>

<ResponseField name="orders" type="object">
  Structured orders returned on note submission. For Medication orders, read **`orders.medication_orders`** with **`values`** and **`partial_values`**.
</ResponseField>

<Note>
  For **`noteId`**, **`encounterId`**, and **`contents`**, refer to [Response fields](/web-sdk/guides/note-management#response-fields) in Note management.
</Note>

## Medication order payload structure

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

```json JSON theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
{
  "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.

<Expandable title="Medication order fields" defaultOpen={true}>
  <ResponseField name="drug_name" type="string" required>
    Full medication name (for example `Lisinopril`). This field is required when Medication orders are enabled in your Web SDK integration.
  </ResponseField>

  <ResponseField name="medication_code" type="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.
  </ResponseField>

  <ResponseField name="dosage" type="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`).
  </ResponseField>

  <ResponseField name="frequency" type="object">
    Administration frequency.

    * **`raw_value`:** Human-readable frequency.
    * **`structured_value`:** Structured value (for example `ONE_A_DAY`).
  </ResponseField>

  <ResponseField name="instructions" type="string">
    Free-form sig or patient instructions.
  </ResponseField>

  <ResponseField name="medication_timing" type="object">
    Timing modifiers.

    * **`raw_value`:** Human-readable timing. For example `In the morning`.
    * **`structured_value`:** Structured value. For example `IN_THE_MORNING`.
  </ResponseField>

  <ResponseField name="strength" type="object">
    Medication strength. Includes **`raw_value`**. For example `10mg`.
  </ResponseField>

  <ResponseField name="format" type="object">
    Dosage form. Includes **`raw_value`**. For example `Tablet`.
  </ResponseField>

  <ResponseField name="route" type="object">
    Route of administration. Includes **`raw_value`** (for example `By mouth`).
  </ResponseField>

  <ResponseField name="linked_diagnosis_codes" type="array">
    Diagnoses linked to the order. Each entry includes **`type`** (for example `ICD10`) and **`code`**.
  </ResponseField>

  <ResponseField name="number_of_refills" type="integer">
    Number of refills when specified.
  </ResponseField>

  <ResponseField name="start_date" type="string">
    Start date-time in RFC3339 format. For example `2026-01-01T00:00:00Z`.
  </ResponseField>

  <ResponseField name="end_date" type="string">
    End date-time in RFC3339 format.
  </ResponseField>

  <ResponseField name="duration_in_days" type="integer">
    Duration in days when specified.
  </ResponseField>

  <ResponseField name="status" type="string">
    Order status: **`ACTIVE`**, **`DISCONTINUED`**, or **`REFILLED`**.
  </ResponseField>

  <ResponseField name="metadata" type="object">
    Provenance for the order.

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

    <Note>
      When origin is `EMR`, the `encounter_relation` field is **required**.
    </Note>
  </ResponseField>
</Expandable>

## Example code

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

<View title="JavaScript" icon="js">
  ```js JavaScript theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  const unsubscribe = sdkClient.on("note-submission:success", (payload) => {
    console.log("Note ID:", payload.noteId);
    console.log("Encounter ID:", payload.encounterId);

    const medOrders = payload.orders?.medication_orders ?? {};
    const values = medOrders.values ?? [];
    const partialValues = medOrders.partial_values ?? [];

    values.forEach((order) => {
      console.log("Order:", order.drug_name, order.status);
    });

    partialValues.forEach((order) => {
      console.log("Partial order:", order.drug_name);
    });
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx React theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useCallback } from "react";

  const handleNoteSubmit = useCallback((payload) => {
    const medOrders = payload.orders?.medication_orders ?? {};
    const values = medOrders.values ?? [];
    const partialValues = medOrders.partial_values ?? [];

    values.forEach((order) => {
      saveOrderToEhr(order);
    });

    partialValues.forEach((order) => {
      queueForManualReview(order);
    });
  }, []);

  return <SukiAssistant onNoteSubmit={handleNoteSubmit} />;
  ```
</View>

## Best practices

<Tip>
  * 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.
</Tip>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to [Medication orders overview](/web-sdk/medication-orders/overview) to enable Medication orders in your Web SDK integration.

<Icon icon="file-lines" iconType="solid" /> Refer to [Medication orders error codes](/web-sdk/medication-orders/error-codes) to handle errors during medication order generation.