diff --git a/documentation/how_to/upgrade.md b/documentation/how_to/upgrade.md
index 6d6e2fed..ad3ebfd0 100644
--- a/documentation/how_to/upgrade.md
+++ b/documentation/how_to/upgrade.md
@@ -19,6 +19,17 @@ This section contains each breaking change, and the steps required to address it
 
 If you use `Ash.Flow`, include `{:ash_flow, "~> 0.1.0"}` in your application.
 
+### Ash.Api is now Ash.Domain
+
+The previous name was often confusing as this is an overloaded term for many. To that end, `Ash.Api` has been renamed to `Ash.Domain`, which better fits our usage and concepts.
+
+#### What you'll need to change
+
+To make this change you will need to do two things:
+
+1. replace `Ash.Api` with `Ash.Domain` in your application
+2. replace places where an `:api` option is passed to a function with the `:domain` option. For example, `AshPhoenix.Form.for_create(..., api: MyApp.SomeApi)` should now be `AshPhoenix.Form.for_create(..., domain: MyApp.SomeDomain)`
+
 ### DSL Changes
 
 - `code_interface.define_for` is now `code_interface.domain`. Additionally, it is set automatically if the `domain` option is specified on `use Ash.Resource`.
@@ -161,19 +172,6 @@ Additionally, the following exceptions have had keys remapped:
 
 ## Significant Changes
 
-### Ash.Api is now Ash.Domain
-
-The previous name was often confusing as this is an overloaded term for many. To that end, `Ash.Api` has been renamed to `Ash.Domain`, which better fits our usage and concepts.
-
-#### What you'll need to change
-
-To make this change you will need to do two things:
-
-1. replace `Ash.Api` with `Ash.Domain` in your application
-2. replace places where an `:api` option is passed to a function with the `:domain` option. For example, `AshPhoenix.Form.for_create(..., api: MyApp.SomeApi)` should now be `AshPhoenix.Form.for_create(..., domain: MyApp.SomeDomain)`
-
----
-
 ### the `Domain` of a resource must now be known when constructing a changeset, query or action input
 
 In order to honor rules on the `Domain` module about authorization and timeouts, we have to know the `Domain` when building the changeset.