---
title: "Update Order"
method: PATCH
path: "/v3/order/{order_id}"
tags: ["order"]
---

# Update Order

`PATCH /v3/order/{order_id}`

Update a modifiable order's scheduled activation date.

The order must be in `ordered` or `awaiting_registration` status. Setting
`activate_by` to a future date reschedules dispatch; setting it to `null`
clears the schedule and enqueues immediate dispatch for `ordered` orders.

Returns 400 when:
- the order is not in a modifiable status,
- the order was created for immediate processing (cannot be scheduled
  after the fact),
- `activate_by` is in the past.

## Path parameters

- `order_id` string, uuid, required — Your Order ID.

## Request body

- UpdateOrderBody — Patch body for updating a modifiable order's scheduled activation date.
  - `activate_by` string, date, nullable, required — The date on which the order should be activated (dispatched to the lab). Must be today or a future date. Set to `null` to clear an existing scheduled date and dispatch the order immediately. Note: an order originally created for immediate processing (no `activate_by` at creation time) cannot be rescheduled — only orders that were created with an `activate_by` can have it changed or cleared.

## Response `200`

Successful Response

- PostOrderResponse
  - `order` ClientFacingOrder, required
    - `user_id` string, uuid, required — User id returned by vital create user request. This id should be stored in your database against the user and used for all interactions with the vital api.
    - `id` string, uuid, required — The Vital Order ID
    - `team_id` string, uuid, required — Your team id.
    - `patient_details` ClientFacingPatientDetailsCompatible, required
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `dob` string, date-time, required
      - `gender` string, required
      - `phone_number` string, nullable
      - `email` string, nullable
      - `medical_proxy` GuarantorDetails
        - `first_name` string, required
        - `last_name` string, required
        - `address` Address, required
          - `first_line` string, required
          - `second_line` string, nullable
          - `country` string, required
          - `zip` string, required
          - `city` string, required
          - `state` string, required
          - `access_notes` string, nullable
        - `phone_number` string, required
        - `household_income` integer, nullable
        - `household_size` integer, nullable
        - `email` string, nullable
      - `race` 'african_american_or_black' | 'asian' | 'indigenous_native_american_alaska_native' | 'other' | 'pacific_islander_or_hawaiian' | 'white_caucasian' — ℹ️ This enum is non-exhaustive.
      - `ethnicity` 'hispanic' | 'non_hispanic' | 'ashkenazi_jewish' | 'other' — ℹ️ This enum is non-exhaustive.
      - `sexual_orientation` 'lesbian_gay_or_homosexual' | 'heterosexual_or_straight' | 'bisexual' | 'dont_know' | 'other' — ℹ️ This enum is non-exhaustive.
      - `gender_identity` 'male' | 'female' | 'female_to_male_ftm_transgender_male_trans_man' | 'male_to_female_mtf_transgender_female_trans_woman' | 'genderqueer' | 'other' — ℹ️ This enum is non-exhaustive.
    - `patient_address` PatientAddressCompatible, required
      - `receiver_name` string
      - `first_line` string, required
      - `second_line` string, nullable
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `country` string, required
      - `access_notes` string, nullable
      - `phone_number` string, nullable
    - `lab_test` ClientFacingLabTest, required
      - `id` string, uuid, required
      - `slug` string, required
      - `name` string, required
      - `sample_type` 'dried_blood_spot' | 'arm_collector' | 'serum' | 'saliva' | 'urine' | 'stool', required — The type of sample used to perform a lab test. ℹ️ This enum is non-exhaustive.
      - `method` 'testkit' | 'walk_in_test' | 'at_home_phlebotomy' | 'on_site_collection', required — The method used to perform a lab test. ℹ️ This enum is non-exhaustive.
      - `price` number, required
      - `is_active` boolean, required — Deprecated. Use status instead.
      - `status` 'active' | 'pending_approval' | 'inactive', required — ℹ️ This enum is non-exhaustive.
      - `fasting` boolean — Defines whether a lab test requires fasting.
      - `lab` ClientFacingLab, required
        - `id` integer, required
        - `slug` string, required
        - `name` string, required
        - `first_line_address` string, required
        - `city` string, required
        - `zipcode` string, required
        - `collection_methods` LabTestCollectionMethod[], required
        - `sample_types` LabTestSampleType[], required
        - `logo_url` string, nullable
      - `markers` ClientFacingMarker[], nullable, required
        - `id` integer, required
        - `name` string, required
        - `slug` string, required
        - `description` string, nullable
        - `lab_id` integer, nullable
        - `provider_id` string, nullable
        - `type` 'biomarker' | 'panel' — ℹ️ This enum is non-exhaustive.
        - `unit` string, nullable
        - `price` string, nullable
        - `aoe` AoE
          - `questions` Question[], required
            - `id` integer, required
            - `required` boolean, required
            - `code` string, required
            - `value` string, required
            - `type` 'choice' | 'text' | 'numeric' | 'multi_choice', required — ℹ️ This enum is non-exhaustive.
            - `sequence` integer, required
            - `answers` Answer[], required
              - …
            - `constraint` string, nullable
            - `default` string, nullable
        - `a_la_carte_enabled` boolean
        - `common_tat_days` integer, nullable
        - `worst_case_tat_days` integer, nullable
        - `is_orderable` boolean, nullable
      - `is_delegated` boolean — Deprecated and always false. Delegation is now at the lab account level. Used to denote whether a lab test requires using non-Vital physician networks.
      - `auto_generated` boolean — Whether the lab test was auto-generated by Vital
      - `has_collection_instructions` boolean, nullable — Whether or not the lab test has collection instructions.
      - `common_tat_days` integer, nullable — The common turnaround time in days for the lab test. This is the expected time for the lab to process the test and return results.
      - `worst_case_tat_days` integer, nullable — The worst-case turnaround time in days for the lab test. This is the maximum time the lab may take to process the test and return results.
    - `details` union, required
      - ClientFacingWalkInOrderDetails
        - `type` 'walk_in_test', required
        - `data` ClientFacingWalkInTestOrder — Schema for a walk-in test order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Vital walk-in test Order ID
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
          - `appointment_id` string, uuid, nullable
      - ClientFacingTestKitOrderDetails
        - `type` 'testkit', required
        - `data` ClientFacingTestkitOrder — Schema for a testkit order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Vital TestKit Order ID
          - `shipment` ClientFacingShipment, required — Schema for a Shipment in the client facing API. To be used as part of a ClientFacingTestkitOrder.
            - `id` string, uuid, required — The Vital Shipment ID
            - `outbound_tracking_number` string, nullable, required — Tracking number for delivery to customer
            - `outbound_tracking_url` string, nullable, required — Tracking url for delivery to customer
            - `inbound_tracking_number` string, nullable, required — Tracking number for delivery to lab
            - `inbound_tracking_url` string, nullable, required — Tracking url for delivery to lab
            - `outbound_courier` string, nullable, required — Courier used for delivery to customer
            - `inbound_courier` string, nullable, required — Courier used for delivery to lab
            - `notes` string, nullable, required — Notes associated to the Vital shipment
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
      - ClientFacingAtHomePhlebotomyOrderDetails
        - `type` 'at_home_phlebotomy', required
        - `data` ClientFacingAtHomePhlebotomyOrder — Schema for a at-home-phlebotomy test order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Vital at-home phlebotomy Order ID
          - `appointment_id` string, uuid, nullable
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
      - ClientFacingOnSiteCollectionOrderDetails
        - `type` 'on_site_collection', required
        - `data` ClientFacingOnSiteCollectionOrder — Schema for an on-site collection order in the client facing API. To be used as part of a ClientFacingOrder.
          - `id` string, uuid, required — The Junction on-site collection Order ID
          - `created_at` string, date-time, required
          - `updated_at` string, date-time, required
    - `sample_id` string, nullable, required — Sample ID
    - `notes` string, nullable, required — Notes associated with the order
    - `clinical_notes` string, nullable
    - `created_at` string, date-time, required — When your order was created
    - `updated_at` string, date-time, required — When your order was last updated.
    - `events` ClientFacingOrderEvent[], required
      - `id` integer, required
      - `created_at` string, date-time, required
      - `status` 'received.walk_in_test.ordered' | 'received.walk_in_test.requisition_created' | 'received.walk_in_test.requisition_bypassed' | 'completed.walk_in_test.completed' | 'sample_with_lab.walk_in_test.partial_results' | 'failed.walk_in_test.sample_error' | 'cancelled.walk_in_test.cancelled' | 'collecting_sample.walk_in_test.appointment_pending' | 'collecting_sample.walk_in_test.appointment_scheduled' | 'collecting_sample.walk_in_test.appointment_cancelled' | 'collecting_sample.walk_in_test.redraw_available' | 'received.at_home_phlebotomy.ordered' | 'received.at_home_phlebotomy.requisition_created' | 'received.at_home_phlebotomy.requisition_bypassed' | 'collecting_sample.at_home_phlebotomy.appointment_pending' | 'collecting_sample.at_home_phlebotomy.appointment_scheduled' | 'collecting_sample.at_home_phlebotomy.draw_completed' | 'collecting_sample.at_home_phlebotomy.appointment_cancelled' | 'completed.at_home_phlebotomy.completed' | 'sample_with_lab.at_home_phlebotomy.partial_results' | 'cancelled.at_home_phlebotomy.cancelled' | 'failed.at_home_phlebotomy.sample_error' | 'received.testkit.ordered' | 'received.testkit.awaiting_registration' | 'received.testkit.requisition_created' | 'received.testkit.requisition_bypassed' | 'received.testkit.registered' | 'collecting_sample.testkit.transit_customer' | 'collecting_sample.testkit.out_for_delivery' | 'collecting_sample.testkit.with_customer' | 'collecting_sample.testkit.transit_lab' | 'sample_with_lab.testkit.delivered_to_lab' | 'sample_with_lab.testkit.lab_processing_blocked' | 'completed.testkit.completed' | 'failed.testkit.failure_to_deliver_to_customer' | 'failed.testkit.failure_to_deliver_to_lab' | 'failed.testkit.sample_error' | 'failed.testkit.lost' | 'cancelled.testkit.cancelled' | 'cancelled.testkit.do_not_process' | 'collecting_sample.testkit.problem_in_transit_customer' | 'collecting_sample.testkit.problem_in_transit_lab' | 'received.on_site_collection.ordered' | 'received.on_site_collection.requisition_created' | 'received.on_site_collection.requisition_bypassed' | 'sample_with_lab.on_site_collection.draw_completed' | 'completed.on_site_collection.completed' | 'cancelled.on_site_collection.cancelled' | 'sample_with_lab.on_site_collection.partial_results' | 'failed.on_site_collection.sample_error' | 'completed.walk_in_test.corrected' | 'completed.at_home_phlebotomy.corrected' | 'completed.on_site_collection.corrected' | 'completed.testkit.corrected', required — ℹ️ This enum is non-exhaustive.
      - `status_detail` 'fulfillment_error' | 'date_of_collection_unspecified' | 'demographic_information_unspecified' | 'demographic_information_mismatch' | 'sample_quantity_not_sufficient' | 'sample_contaminated' | 'sample_stability_exceeded' | 'sample_hemolyzed' | 'sample_improper_collection' — A descriptive-only additional field to be used in combination with OrderStatus. Exposed in the API. ℹ️ This enum is non-exhaustive.
    - `status` 'received' | 'collecting_sample' | 'sample_with_lab' | 'completed' | 'cancelled' | 'failed' — ℹ️ This enum is non-exhaustive.
    - `last_event` ClientFacingOrderEvent, required
      - `id` integer, required
      - `created_at` string, date-time, required
      - `status` 'received.walk_in_test.ordered' | 'received.walk_in_test.requisition_created' | 'received.walk_in_test.requisition_bypassed' | 'completed.walk_in_test.completed' | 'sample_with_lab.walk_in_test.partial_results' | 'failed.walk_in_test.sample_error' | 'cancelled.walk_in_test.cancelled' | 'collecting_sample.walk_in_test.appointment_pending' | 'collecting_sample.walk_in_test.appointment_scheduled' | 'collecting_sample.walk_in_test.appointment_cancelled' | 'collecting_sample.walk_in_test.redraw_available' | 'received.at_home_phlebotomy.ordered' | 'received.at_home_phlebotomy.requisition_created' | 'received.at_home_phlebotomy.requisition_bypassed' | 'collecting_sample.at_home_phlebotomy.appointment_pending' | 'collecting_sample.at_home_phlebotomy.appointment_scheduled' | 'collecting_sample.at_home_phlebotomy.draw_completed' | 'collecting_sample.at_home_phlebotomy.appointment_cancelled' | 'completed.at_home_phlebotomy.completed' | 'sample_with_lab.at_home_phlebotomy.partial_results' | 'cancelled.at_home_phlebotomy.cancelled' | 'failed.at_home_phlebotomy.sample_error' | 'received.testkit.ordered' | 'received.testkit.awaiting_registration' | 'received.testkit.requisition_created' | 'received.testkit.requisition_bypassed' | 'received.testkit.registered' | 'collecting_sample.testkit.transit_customer' | 'collecting_sample.testkit.out_for_delivery' | 'collecting_sample.testkit.with_customer' | 'collecting_sample.testkit.transit_lab' | 'sample_with_lab.testkit.delivered_to_lab' | 'sample_with_lab.testkit.lab_processing_blocked' | 'completed.testkit.completed' | 'failed.testkit.failure_to_deliver_to_customer' | 'failed.testkit.failure_to_deliver_to_lab' | 'failed.testkit.sample_error' | 'failed.testkit.lost' | 'cancelled.testkit.cancelled' | 'cancelled.testkit.do_not_process' | 'collecting_sample.testkit.problem_in_transit_customer' | 'collecting_sample.testkit.problem_in_transit_lab' | 'received.on_site_collection.ordered' | 'received.on_site_collection.requisition_created' | 'received.on_site_collection.requisition_bypassed' | 'sample_with_lab.on_site_collection.draw_completed' | 'completed.on_site_collection.completed' | 'cancelled.on_site_collection.cancelled' | 'sample_with_lab.on_site_collection.partial_results' | 'failed.on_site_collection.sample_error' | 'completed.walk_in_test.corrected' | 'completed.at_home_phlebotomy.corrected' | 'completed.on_site_collection.corrected' | 'completed.testkit.corrected', required — ℹ️ This enum is non-exhaustive.
      - `status_detail` 'fulfillment_error' | 'date_of_collection_unspecified' | 'demographic_information_unspecified' | 'demographic_information_mismatch' | 'sample_quantity_not_sufficient' | 'sample_contaminated' | 'sample_stability_exceeded' | 'sample_hemolyzed' | 'sample_improper_collection' — A descriptive-only additional field to be used in combination with OrderStatus. Exposed in the API. ℹ️ This enum is non-exhaustive.
    - `physician` ClientFacingPhysician
      - `first_name` string, required
      - `last_name` string, required
      - `npi` string, required
    - `health_insurance_id` string, uuid, nullable, required — Vital ID of the health insurance.
    - `requisition_form_url` string, nullable, required — DEPRECATED. Requistion form url.
    - `priority` boolean — Defines whether order is priority or not. For some labs, this refers to a STAT order.
    - `shipping_details` ShippingAddress, required
      - `receiver_name` string, required
      - `first_line` string, required
      - `second_line` string, nullable
      - `city` string, required
      - `state` string, required
      - `zip` string, required
      - `country` string, required
      - `phone_number` string, required
    - `activate_by` string, date, nullable — Schedule an Order to be processed in a future date.
    - `passthrough` string, nullable
    - `billing_type` 'client_bill' | 'commercial_insurance' | 'patient_bill_passthrough' | 'patient_bill' — ℹ️ This enum is non-exhaustive.
    - `icd_codes` string[], nullable
    - `has_abn` boolean, required — Defines whether the order has an Advanced Beneficiary Notice (ABN) form or not.
    - `interpretation` 'normal' | 'abnormal' | 'critical' | 'unknown' — ℹ️ This enum is non-exhaustive.
    - `has_missing_results` boolean, nullable — Defines whether the order result has missing biomarkers.
    - `expected_result_by_date` string, date, nullable — The common-case date by which the order result is expected to be available.
    - `worst_case_result_by_date` string, date, nullable — The latest date by which the order result is expected to be available.
    - `origin` 'initial' | 'redraw' | 'recreation' — ℹ️ This enum is non-exhaustive.
    - `order_transaction` ClientFacingOrderTransaction — Order transaction info.
      - `id` string, uuid, required
      - `status` 'active' | 'completed' | 'cancelled', required — ℹ️ This enum is non-exhaustive.
      - `orders` ClientFacingOrderInTransaction[], required
        - `id` string, uuid, required
        - `low_level_status` 'ordered' | 'requisition_created' | 'requisition_bypassed' | 'transit_customer' | 'out_for_delivery' | 'with_customer' | 'transit_lab' | 'delivered_to_lab' | 'completed' | 'failure_to_deliver_to_lab' | 'failure_to_deliver_to_customer' | 'problem_in_transit_lab' | 'problem_in_transit_customer' | 'sample_error' | 'appointment_scheduled' | 'appointment_cancelled' | 'appointment_pending' | 'draw_completed' | 'cancelled' | 'lost' | 'do_not_process' | 'partial_results' | 'awaiting_registration' | 'registered' | 'redraw_available' | 'corrected' | 'lab_processing_blocked' — ℹ️ This enum is non-exhaustive.
        - `low_level_status_created_at` string, date-time, nullable
        - `origin` 'initial' | 'redraw' | 'recreation' — ℹ️ This enum is non-exhaustive.
        - `parent_id` string, uuid, nullable
        - `created_at` string, date-time, required
        - `updated_at` string, date-time, required
  - `status` string, required
  - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/tryvital/apis/junction-api.md) · [All operations](https://skmtc.net/tryvital/apis/junction-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryvital/junction-api/versions/d28f5cec7d79/schema)