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.
- Supported camera and doorbell devices, including Matter-capable Google Nest cameras and doorbells as well as compatible partner cameras. For details on supported and unsupported models, see [Cameras and doorbells](https://developers.home.google.com/apis/android/device/remove.md.txt#cameras-doorbells).

## 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.
- Non-camera dual-path devices (devices that implement both Matter and Cloud-to-cloud, other than supported cameras and doorbells).
- Unsupported camera and doorbell devices, including smart displays with built-in cameras and legacy cameras that don't support Matter (see [Cameras and doorbells](https://developers.home.google.com/apis/android/device/remove.md.txt#cameras-doorbells)).

## 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:

- If a device provides multiple functions, such as 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 are affected.
- Removing a camera or doorbell permanently deletes all 24/7 video history, event video history, recorded clips, and familiar face library data associated with that camera across the entire home structure.
- Decommissioning a camera does not cancel active subscriptions, such as Google Home Premium or partner monitoring services. Subscriptions continue until cancelled by the user.
- When decommissioning a camera or doorbell, the Home APIs platform presents a Google-managed confirmation screen to the user explaining that video history will be permanently erased. The user must confirm this prompt before the device is removed.
- Be cautious when deleting devices on shared surfaces, because this can have unintended consequences for others.
- Device removal must 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.md.txt).

## 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]
> **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!")
}
```

### Cameras and doorbells

You can remove supported cameras and doorbells programmatically using
`decommissionDevice()`
.

Supported models include:

- Google Nest Cam (indoor, wired)
- Google Nest Cam (outdoor or indoor, battery)
- Google Nest Cam with floodlight
- Google Nest Doorbell (battery)
- Google Nest Doorbell (wired)
- Compatible partner cameras and doorbells (such as Walmart onn.)

The following camera and doorbell devices cannot be decommissioned
programmatically:

- Smart displays with built-in cameras, such as Google Nest Hub Max.
- Legacy Nest cameras and doorbells that don't support Matter and connect only through cloud services, such as Nest Cam Indoor (1st gen), Nest Cam Outdoor (1st gen), Nest Cam IQ, and Nest Doorbell (wired, 1st gen).
- Third-party Cloud-to-cloud linked cameras and doorbells.

When your app initiates decommissioning for a camera or doorbell, the
platform displays a Google-managed confirmation screen to the user. This screen
informs the user that removing the camera permanently deletes all recorded
24/7 video history, event history, clips, and familiar face library data
associated with the device across the entire structure.
If the user dismisses or cancels the confirmation screen, `decommissionDevice()` throws a `HomeException`.

Decommissioning a camera does not cancel active camera subscriptions (such as
Google Home Premium). Users must cancel subscriptions separately through
the subscription provider.

```kotlin
try {
  val decommissionedDeviceIds = device.decommissionDevice()
  if (decommissionedDeviceIds.contains(device.id)) {
    // Camera was successfully decommissioned
  }
} catch (e: HomeException) {
  // Handle cancellation or decommission error
}
```

### Non-Matter devices

Non-Matter devices (other than supported cameras and
doorbells) cannot be removed programmatically. To remove other
non-Matter devices, you can issue a Sync request (see
[Request Sync](https://developers.home.google.com/cloud-to-cloud/integration/request-sync.md.txt)), 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 an unsupported
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!")
}
```