From 21c528991685285cf989ccc6bcde1f05a9291dd6 Mon Sep 17 00:00:00 2001
From: Andrew Sayre <6730289+andrewsayre@users.noreply.github.com>
Date: Mon, 7 Apr 2025 09:57:45 -0500
Subject: [PATCH] Document HEOS entity service to move queue items (#38387)

* Document remove_from_queue

* Correct example
---
 source/_integrations/heos.markdown | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/source/_integrations/heos.markdown b/source/_integrations/heos.markdown
index 11bd64c45c4..c1dd47478ef 100644
--- a/source/_integrations/heos.markdown
+++ b/source/_integrations/heos.markdown
@@ -87,7 +87,7 @@ In addition to the standard [Media Player actions](/integrations/media_player#ac
 
 Group volume actions: `heos.group_volume_set`, `heos.group_volume_down`, and `heos.group_volume_up` for entities joined to a group.
 
-Queue actions: `heos.get_queue` and `heos.remove_from_queue` to manage a player's queue items.
+Queue actions: `heos.get_queue`, `heos.move_queue_item`, and `heos.remove_from_queue` to manage a player's queue items.
 
 ### Action `heos.group_volume_set`
 
@@ -129,6 +129,27 @@ media_player.office:
       album_id: "134788273"
 ```
 
+### Action `heos.move_queue_item`
+
+Move one or more items in the target player's queue, effectively reordering the play queue. The play queue can be enumerated by using the `heos.get_queue` service.
+
+Example action data payload that moves the second item to the top of the play queue:
+
+```yaml
+action: heos.move_queue_item
+target:
+  entity_id: media_player.family_room_receiver
+data:
+  queue_ids:
+    - 2
+  destination_position: 1
+```
+
+| Data attribute | Optional | Description                                                     |
+| ---------------------- | -------- | ------------------------------------------------------- |
+| `queue_ids`            | no       | The IDs (indexes) of the items in the queue to move.    |
+| `destination_position` | no       | The destination position in the queue (starting at 1).  |
+
 ### Action `heos.remove_from_queue`
 
 Removes one or more items from the target player(s) queue. The play queue can be enumerated by using the `heos.get_queue` service. Example action data payload: