wp_reorder_menu_items: reorder menu items
Sets the order of menu items by listing their IDs in the sequence you want.
Arguments
| Argument | Required | Meaning |
|---|---|---|
menu_id |
Yes | The menu |
items |
Yes | 1–200 unique item IDs belonging to this menu, in the intended order |
dry_run |
No | Report without writing |
Permissions
Allow content writes open, and edit_theme_options.
How it works
Each item in the array is assigned a position matching its place in the list — first, second, third, and so on. The order of the array is the resulting order.
Pass the complete list
The tool only touches the items you name. Any item you omit keeps whatever position it had.
That is the property to plan around: a partial list produces a mixture of new and old positions, which can leave two items sharing a position and an order that looks arbitrary.
Read the menu first and send every item:
Show me the items in menu 3 with their IDs and current order. Then set this order: 12, 45, 88, 91, 103.
State the result, not a move
An instruction like "move Contact up one" depends on the assistant's understanding of the current order — which is exactly the thing you should not leave to inference.
Give the intended end state as a full sequence. It is unambiguous, and it is verifiable against the listing you just read.
Hierarchy is separate from order
This tool sets position only. It does not change which item is a child of which.
To restructure the hierarchy, use wp_update_menu_item with parent. A common sequence is: re-parent the items that need moving, then reorder within their new level.
Note that ordering applies within a level. Reordering a mixed list of top-level items and sub-items produces positions that only make sense once you account for the hierarchy — which is another reason to read parent alongside order before starting.
The dry run
Returns current positions and the list it would apply. Worth checking against the listing you read, because a transposed ID in a long sequence is easy to make and hard to spot afterwards.
What it returns
Returns complete and the number updated. Invalid or foreign IDs are rejected before approval. A storage failure returns complete: false and failed_item_id; earlier updates remain applied. Inspect the menu before requesting another operation.
After reordering
Menus are on every page:
- Open the site and read the menu left to right.
- Open each dropdown.
- Check mobile, where order can matter more because everything is vertical.
- Purge the cache.
Multilingual sites
Each language's menu is ordered independently. Reordering one leaves the others as they were, and navigation that reads in a different order per language is usually unintentional.
Common problems
| Symptom | Cause |
|---|---|
| The write is refused | Content write gate closed |
pom_ai_mcp_forbidden |
No edit_theme_options |
| The order is partly wrong | An incomplete list; omitted items kept their old positions |
| Two items appear interchangeable | They ended up with the same position |
| Sub-items moved oddly | Ordering is within a level; check parent |
complete: false |
Storage failed after execution began; inspect failed_item_id |
| The site shows the old order | Cache not purged |
Related
wp_get_menu_items— read the current order firstwp_update_menu_itemfor hierarchy- Edit a navigation menu