Removing a device involves decommissioning it from the structure. A user can
do this using the Google Home app (GHA), and an app can programmatically
decommission a smart home device. There are limitations as to which devices can
be removed. Also, removing a device can affect your structure and user
experiences for your app.

## What you can remove

You can programmatically remove the following devices through the Home APIs:

- Matter devices for which your app has permissions.
- Matter bridges, provided your app has access to all the devices connected through the bridge. Removing the bridge removes all Matter devices connected to it.

## What you cannot remove

The following devices can't be removed programmatically through the Home APIs:

- Matter devices for which your app lacks user permissions.
- Individual devices connected behind a Matter bridge.
- Cloud-to-cloud linked devices.
- Dual-path devices (devices that implement both Matter and Cloud-to-cloud).

## Important considerations before removing a device

When your app removes a device, it is removed from the entire
structure, affecting all users and all apps, including
the GHA. Depending on what type of device it is, there may
be additional side effects of decommissioning a device:

- Devices implementing multiple device types: If a device has multiple functions - for example, a smart light that also acts as a hub, removing it also removes all associated devices. The app should inform the user if multiple device functions will be affected.
- Device History: Deleting a device may result in the removal of the device's history.
- Shared Surfaces: Be cautious when deleting devices on shared surfaces, because this can have unintended consequences for others.
- Authentication: Device removal should only be performed on authenticated surfaces, such as a mobile phone, not on unauthenticated devices like TVs. Doing so violates the [Google Home Developer Policies](https://developers.home.google.com/policies).

## Remove a device

Checking a device's eligibility to be removed is costly and should only be done
when necessary. To check if a device is eligible to be removed, use the
following command:  

```kotlin
val eligibility = device.checkDecommissionEligibility()

if (eligibility is DecommissionEligibility.Ineligible) {
  println("The device cannot be decommissioned.")
} else if (eligibility is DecommissionEligibility.EligibleWithSideEffects) {
  println("The device can be decommissioned but there will be side effects on other devices.")
} else if (eligibility is DecommissionEligibility.Eligible) {
  println("The device can be decommissioned.")
}
```
| **Important:** This API is resource-intensive and can incur significant latency. Developers should be careful not to allow this latency to impact user interface responsiveness.

### Matter devices

You can remove a Matter device programmatically if the
device isn't behind a Matter bridge.

To remove a Matter device, call
`decommissionDevice()`
on it:  

```kotlin
val decommissionedDeviceIds = device.decommissionDevice()
```

If the call doesn't throw an error, it succeeded.

You may check to see if the device's ID is among those returned by the
`decommissionDevice()`
:  

```kotlin
if (decommissionedDeviceIds.contains(deviceId)) {
  println("Decommission successful!")
} else {
  println("Decommission failed!")
}
```

### Non-Matter devices

Non-Matter devices cannot be removed programmatically. To
remove a non-Matter device, you can
issue a Sync request (see [Request
Sync](https://developers.home.google.com/cloud-to-cloud/integration/request-sync)),
or delete the Cloud-to-cloud integration (see
[Delete a launched Cloud-to-cloud
integration](https://developers.home.google.com/cloud-to-cloud/on-hold/launch/delete)).

If you call `decommissionDevice()` on a
non-Matter device, a `HomeException`

is thrown.

Once you remove a non-Matter device, check for the presence
of the device to verify it was successfully removed:  

```kotlin
var removedDevice: HomeDevice? = null
runBlockingCustom {
  try {
    removedDevice = homeManager.devices().get(deviceId)
  } catch (exception: Exception) {
    println("removal successful!")
  }
}
if (removedDevice != null) {
  println("removal failed!")
}
```

### Multi-source devices

*Multi-source* devices are devices that use both Cloud-to-cloud and
Matter APIs. If you check the decommission eligibility
of such a device, you'll get a

[`DecommissionIneligibleReason.multiSourceDevice`](https://developers.home.google.com/reference/kotlin/com/google/home/DecommissionIneligibleReason.multiSourceDevice),
indicating that because the device is multi-source, it can't be decommissioned.

To remove a multi-source device, use the following procedure:

1. Remove the Cloud-to-cloud association as described in [Non-Matter devices](https://developers.home.google.com/apis/android/device/remove#non-matter_devices).
2. Decommission the Matter device as described in [Matter devices](https://developers.home.google.com/apis/android/device/remove#matter_devices).

The order of these steps is important. If you attempt to
decommission the Matter device before removing the
Cloud-to-cloud association, a
`HomeException`
is thrown.