Removing a device involves decommissioning it from the structure. A user can do this using theGoogle 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:

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

## What you cannot remove

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

- Matterdevices for which your app lacks user permissions.
- Individual devices connected behind aMatterbridge.
- Cloud-to-cloudlinked devices.
- Dual-path devices (devices that implement bothMatterandCloud-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 theGHA. 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 aMatterdevice programmatically if the device isn't behind aMatterbridge.

To remove aMatterdevice, 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-Matterdevices cannot be removed programmatically. To remove a non-Matterdevice, you can issue a Sync request (see[Request Sync](https://developers.home.google.com/cloud-to-cloud/integration/request-sync)), or delete theCloud-to-cloudintegration (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-Matterdevice, a`HomeException`is thrown.

Once you remove a non-Matterdevice, 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 bothCloud-to-cloudandMatterAPIs. 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 theCloud-to-cloudassociation as described in[Non-Matter devices](https://developers.home.google.com/apis/android/device/remove#non-matter_devices).
2. Decommission theMatterdevice 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 theMatterdevice before removing theCloud-to-cloudassociation, a`HomeException`is thrown.