diff --git a/.changeset/three-bubbles-there.md b/.changeset/three-bubbles-there.md
new file mode 100644
index 0000000000..5b5e442c4a
--- /dev/null
+++ b/.changeset/three-bubbles-there.md
@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': patch
+---
+
+Added a warning that the `v10` Internet Header requires requesting a new Portal configuration and will not work with the old `v9` format.
diff --git a/apps/documentation/src/stories/misc/migration-guide/migrationv9-10.component.ts b/apps/documentation/src/stories/misc/migration-guide/migrationv9-10.component.ts
index feeefe4b9f..73daa3cd4a 100644
--- a/apps/documentation/src/stories/misc/migration-guide/migrationv9-10.component.ts
+++ b/apps/documentation/src/stories/misc/migration-guide/migrationv9-10.component.ts
@@ -98,6 +98,7 @@ export class MigrationV910Component extends LitElement {
       tag: false,
     },
     internet_header: {
+      request_config: false,
       update_package: false,
       add_text_props: false,
       remove_props: false,
@@ -1447,7 +1448,47 @@ export class MyComponent {
                   ? html`
                       <section>
                         <h4>Internet Header (@swisspost/internet-header)</h4>
+                        <post-banner type="warning" class="mb-16">
+                          <p>
+                            Version 10 uses a <strong>new configuration format</strong>. Your
+                            existing v9 Portal configuration will not work with the v10 Internet
+                            Header and will cause errors at runtime. You must request a
+                            configuration migration <strong>before</strong> upgrading the package.
+                          </p>
+                        </post-banner>
                         <ul class="list-unstyled">
+                          <li class="mb-16">
+                            <div class="form-check">
+                              <input
+                                id="internet_header-request_config"
+                                class="form-check-input"
+                                type="checkbox"
+                                ?checked="${this.state.internet_header.request_config}"
+                              />
+                              <label class="form-check-label" for="internet_header-request_config">
+                                Request a configuration migration to the v10 format
+                                <span class="info">
+                                  <p>
+                                    The v10 Internet Header uses a new Portal configuration format.
+                                    Your existing v9 configuration is incompatible and will cause
+                                    runtime errors after upgrading.
+                                  </p>
+                                  <p>
+                                    Contact the Post Portal Team at
+                                    <a href="mailto:dm-tec@post.ch">dm-tec@post.ch</a> to request a
+                                    configuration migration. Provide your
+                                    <code>serviceId</code> (project ID) and the environments you
+                                    need migrated (e.g. <code>int01</code>, <code>int02</code>,
+                                    <code>prod</code>).
+                                  </p>
+                                  <p>
+                                    Do not upgrade the <code>@swisspost/internet-header</code>
+                                    package until the new configuration is in place.
+                                  </p>
+                                </span>
+                              </label>
+                            </div>
+                          </li>
                           <li class="mb-16">
                             <div class="form-check">
                               <input
diff --git a/apps/documentation/src/stories/packages/internet-header/internet-header.docs.mdx b/apps/documentation/src/stories/packages/internet-header/internet-header.docs.mdx
index 80a60ee835..6607bc2e78 100644
--- a/apps/documentation/src/stories/packages/internet-header/internet-header.docs.mdx
+++ b/apps/documentation/src/stories/packages/internet-header/internet-header.docs.mdx
@@ -30,6 +30,19 @@ import { PackageShields } from '@root/src/shared/package-shields';
       <p>The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header.
       <br/>If you're working on a new project, you probably need a new configuration. Please contact the Post Portal Team.</p>
 
+      <post-banner type="warning" className="mt-16 mb-16">
+        <h4 slot="heading">Migrating from v9?</h4>
+        <p>
+          Version 10 uses a <strong>new configuration format</strong>. Your existing v9
+          configuration <strong>will not work</strong> with the v10 header and will cause
+          errors at runtime. Before upgrading, contact the Post Portal Team at{' '}
+          <a href="mailto:dm-tec@post.ch" rel="noopener">dm-tec@post.ch <post-icon name="letter" /></a>{' '}
+          to request a <strong>configuration migration</strong> to the v10 format. Provide your
+          project's <code>serviceId</code> and the environments you need migrated
+          (e.g. <code>int01</code>, <code>int02</code>, <code>prod</code>).
+        </p>
+      </post-banner>
+
       <h3>Step 1</h3>
       <p>Integration of header only: contact <a href="mailto:dm-tec@post.ch" rel="noopener">dm-tec@post.ch <post-icon name="letter" /></a> directly</p>
       <p>Integration of header and KLP: contact KLP first for integration</p>