apple_device-management/mdm/commands/system.update.schedule.yaml

title: Schedule OS Update Command
description: Schedule an update of the operating system on a device.
payload:
  requesttype: ScheduleOSUpdate
  supportedOS:
    iOS:
      introduced: '9.0'
      deprecated: '26.0'
      accessrights: AllowAppInstallation
      supervised: true
      requiresdep: false
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: false
      userenrollment:
        mode: forbidden
    macOS:
      introduced: '10.11'
      deprecated: '26.0'
      accessrights: None
      devicechannel: true
      userchannel: false
      supervised: true
      requiresdep: false
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: '12.0'
      deprecated: '26.0'
      accessrights: AllowAppInstallation
      devicechannel: true
      supervised: true
      requiresdep: false
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  content: This command allows the server to schedule an OS update.
payloadkeys:
- key: Updates
  type: <array>
  presence: required
  content: |-
    An array of dictionaries specifying the updates to download or install. If this value is missing, the device applies the default behavior for handling updates.
    The device ignores this command and an informational error is returned, if a software update is managed by a Declarative Device Management `SoftwareUpdateEnforcementSpecific` configuration, as the configuration takes precedence.
  subkeys:
  - key: UpdatesItem
    type: <dictionary>
    presence: required
    content: A dictionary that describes the available operating-system updates item.
    subkeys:
    - key: ProductKey
      type: <string>
      presence: optional
      content: The product key that represents the update.
    - key: ProductVersion
      supportedOS:
        iOS:
          introduced: '11.3'
        macOS:
          introduced: '12.0'
        tvOS:
          introduced: '12.2'
      type: <string>
      presence: optional
      content: |-
        The version of the update, which the system requires if `ProductKey` isn't present. This value is available in iOS 11.3 and later, macOS 12 and later, and tvOS 12.2 and later.

        > Note:
        > This value isn't available for use with Background Security Improvement updates.
    - key: InstallAction
      type: <string>
      presence: required
      rangelist:
      - Default
      - DownloadOnly
      - InstallASAP
      - NotifyOnly
      - InstallLater
      - InstallForceRestart
      content: |-
        The install action, which is one of the following values:

        - `Default`: Download or install the update, depending on the current state. You can check the `UpdateResults` dictionary to review scheduled updates. This value is available in iOS 9 and later, macOS 10.11 and later, and tvOS 12 and later.
        - `DownloadOnly`: Download the software update without installing it. This value is available in iOS 9 and later, macOS 11 and later, and tvOS 12 and later.
        - `InstallASAP`: In iOS and tvOS, install a previously downloaded software update. In macOS, download the software update and trigger the restart countdown notification. This value is available in iOS 9 and later, macOS 10.11 and later, and tvOS 12 and later.
        - `NotifyOnly`: Download the software update and notify the user through the App Store. This value is available in macOS 10.11 and later.
        - `InstallLater`: Download the software update and install it at a later time. This value is available in macOS 10.11 and later.
        - `InstallForceRestart`: Perform the `Default` action, and then force a restart if the update requires it. This value is available in macOS 11 and later.


        > Warning:
        > `InstallForceRestart` may result in data loss.
    - key: MaxUserDeferrals
      supportedOS:
        iOS:
          introduced: n/a
        macOS:
          introduced: '12.0'
        tvOS:
          introduced: n/a
      type: <integer>
      presence: optional
      content: |-
        The maximum number of times the system allows the user to postpone an update before it's installed. The system prompts the user once a day.

        This key is only supported when `InstallAction` is `InstallLater` and only supported for minor OS updates (for example, macOS 12.x to 12.y).
    - key: Priority
      supportedOS:
        iOS:
          introduced: n/a
        macOS:
          introduced: '12.3'
        tvOS:
          introduced: n/a
      type: <string>
      presence: optional
      rangelist:
      - Low
      - High
      default: Low
      content: |-
        The scheduling priority for downloading and preparing the requested update. This is only supported for minor OS updates (macOS 12.x to 12.y).

        Available in macOS 12.3 and later. Prior versions of macOS used a priority of `Low`.
responsekeys:
- key: UpdateResults
  type: <array>
  presence: required
  content: An array of dictionaries that describes the results of processing operating-system
    updates.
  subkeys:
  - key: UpdateResultsItem
    type: <dictionary>
    presence: required
    content: The response dictionary that describes the result of processing an operating-system
      update.
    subkeys:
    - key: ProductKey
      type: <string>
      presence: required
      content: The product key that represents the update.
    - key: InstallAction
      type: <string>
      presence: required
      rangelist:
      - Error
      - DownloadOnly
      - InstallASAP
      - NotifyOnly
      - InstallLater
      - InstallForceRestart
      content: |-
        The install action that the device scheduled, which is one of the following values:

        - `Error`: An error occurred during scheduling.
        - `DownloadOnly`: Download the software update without installing it.
        - `InstallASAP`: Install a previously downloaded software update.
        - `NotifyOnly`: Download the software update and notify the user through the App Store. This value is available in macOS 10.11 and later.
        - `InstallLater`: Download the software update and install it at a later time. This value is available in macOS 10.11 and later.
        - `InstallForceRestart`: Perform the `Default` action, and then force a restart if the update requires it. This value is available in macOS 11 and later.
    - key: Status
      type: <string>
      presence: required
      rangelist:
      - Idle
      - Downloading
      - DownloadFailed
      - DownloadRequiresComputer
      - DownloadInsufficientSpace
      - DownloadInsufficientPower
      - DownloadInsufficientNetwork
      - Installing
      - InstallInsufficientSpace
      - InstallInsufficientPower
      - InstallPhoneCallInProgress
      - InstallFailed
      content: |-
        The status of the update, which is one of the following values:

        - `Idle`: The update is idle.
        - `Downloading`: The software update is downloading.
        - `DownloadFailed`: The download failed.
        - `DownloadRequiresComputer`: Tether the device to download this update. This value is only available in iOS.
        - `DownloadInsufficientSpace`: There isn't enough space to download the update.
        - `DownloadInsufficientPower`: There isn't enough power to download the update.
        - `DownloadInsufficientNetwork`: The network capacity is insufficient to download the update.
        - `Installing`: The software update is installing.
        - `InstallInsufficientSpace`: There isn't enough space to install the update.
        - `InstallInsufficientPower`: There isn't enough power to install the update.
        - `InstallPhoneCallInProgress`: Installation couldn't occur because a phone call is in progress.
        - `InstallFailed`: Installation failed due to an unspecified reason.
    - key: ErrorChain
      type: <array>
      presence: optional
      content: A dictionary that describes an error chain.
      subkeys:
      - key: ErrorChainItem
        type: <dictionary>
        content: A dictionary that describes an error chain item.
        subkeys:
        - key: ANY
          type: <any>
          presence: required
          content: The error details.
notes:
- title: ''
  content: |-
    Only supervised iOS, macOS, and tvOS devices are eligible for software update management.

    This command can only schedule operating-system updates in iOS and tvOS, however, it can also schedule a variety of system software updates in macOS.

    Downloading and installing updates in iOS and tvOS is a two-step process. Send a `ScheduleOSUpdate` command with `Default` for `InstallAction` to download the updates. Then send another `ScheduleOSUpdate` command with a `Default` `InstallAction` to install the updates. Software updates may require a restart, which prevents the device from responding. When this happens, the MDM server resends the `ScheduleOSUpdate` command when the device checks in again, however, the device won't return a value for `UpdateResults`.

    This command uses the `UpdatesItem` `InstallAction` values to offer varying degrees of control to the user of a device. The user can control the update with the `NotifyOnly` and `DownloadOnly` actions, which don't initiate the update process at all. The `InstallASAP` and `InstallForceRestart` actions attempt to install the update as soon as possible. On iOS devices with a passcode, the user must authorize the update by entering their passcode, allowing them to defer the update a limited number of times. After the user reaches that limit, the system prompts to update every time the device returns to the Home Screen. This makes the device virtually unusable until the user approves the software update. On macOS devices, the `InstallLater` action provides a similar behavior, which specifies how many times the user may defer the update before it's forced.

    A device may return a different `InstallAction` than requested.

    Refer to the following sections to determine supported channels and requirements, and to see an example request and response.