diff --git a/docs/upgrade-guides/2-17-0-to-2-18-0.md b/docs/upgrade-guides/2-17-0-to-2-18-0.md
index e765017..9055058 100644
--- a/docs/upgrade-guides/2-17-0-to-2-18-0.md
+++ b/docs/upgrade-guides/2-17-0-to-2-18-0.md
@@ -2,3 +2,19 @@
 
 This document describes the upgrade instructions from `2.17.0` to `2.18.0`.
 
+### MissionModelId type change
+
+The Merlin portion of the Aerie backend codebase now uses a **numerical** `MissionModelId` record instead of a raw String to represent model ids. This makes it consistent with the rest of the codebase and the database.
+
+This change may impact users who are using the following API actions:
+
+- `getModelEffectiveArguments`
+- `getActivityEffectiveArguments`
+- `getActivityEffectiveArgumentsBulk`
+- `constraintsDslTypescript`
+- `validateActivityArguments`
+- `validateModelArguments`
+
+You will be impacted **only** if you are using a query variable for the `missionModelId` argument of these actions. If so, update your usage by changing the type of that query variable from `ID!` to `Int!`.
+
+You can see an example of this type of change in [this aerie-ui pull request](https://github.com/NASA-AMMOS/aerie-ui/pull/1427/files) for reference.