Add Customer Account EXAF address types

Expose structured extended address fields and address codes on the
Customer Account mailing address API so public extension types and
reference docs match the runtime data provided by Customer Account Web.

Co-authored-by: GPT-5.5 <noreply@openai.com>
Orchestrated-by: ae <noreply@shopify.com>

Author: marcelobarreto

.changeset/customer-account-exaf-addresses.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+Add structured extended address fields to Customer Account order address APIs.

packages/ui-extensions/docs/surfaces/customer-account/build-docs.mjs

@@ -68,6 +68,90 @@ const cleanupTempFiles = async (tempFiles) => {
   );
 };
 
+const customerAccountMailingAddressFields = [
+  {
+    filePath: 'src/surfaces/customer-account/api/shared.ts',
+    syntaxKind: 'PropertySignature',
+    name: 'extendedFields',
+    value: 'AddressExtendedFields',
+    description:
+      'Structured address components for countries and regions that collect them. Values are `null` when the address only has flat address lines.',
+    isOptional: true,
+  },
+  {
+    filePath: 'src/surfaces/customer-account/api/shared.ts',
+    syntaxKind: 'PropertySignature',
+    name: 'addressCode',
+    value: 'string | null',
+    description:
+      'A country-specific address code, such as a short code or postal delivery code.',
+    isOptional: true,
+    examples: [
+      {
+        title: 'Example',
+        description: '',
+        tabs: [{code: "'01001-000'", title: 'Example'}],
+      },
+    ],
+  },
+];
+
+const customerAccountMailingAddressValue = `  /**
+   * Structured address components for countries and regions that collect them.
+   * Values are \`null\` when the address only has flat address lines.
+   */
+  extendedFields?: AddressExtendedFields;
+
+  /**
+   * A country-specific address code, such as a short code or postal delivery code.
+   *
+   * @example '01001-000'
+   */
+  addressCode?: string | null;
+
+`;
+
+const addCustomerAccountMailingAddressDocs = async (generatedDocsV2Path) => {
+  const content = await fs.readFile(generatedDocsV2Path, 'utf8');
+  const generatedDocs = JSON.parse(content);
+  const mailingAddressDocs = generatedDocs.MailingAddress;
+
+  if (!mailingAddressDocs) return;
+
+  const [sourcePath] = Object.keys(mailingAddressDocs);
+  const docs = mailingAddressDocs[sourcePath];
+
+  if (!docs?.members || !docs?.value) return;
+
+  const existingMemberNames = new Set(
+    docs.members.map((member) => member.name),
+  );
+
+  const missingFields = customerAccountMailingAddressFields.filter(
+    (field) => !existingMemberNames.has(field.name),
+  );
+
+  if (missingFields.length > 0) {
+    const address2Index = docs.members.findIndex(
+      (member) => member.name === 'address2',
+    );
+    const insertIndex = address2Index === -1 ? docs.members.length : address2Index + 1;
+    docs.members.splice(insertIndex, 0, ...missingFields);
+  }
+
+  if (!docs.value.includes('extendedFields?: AddressExtendedFields;')) {
+    docs.value = docs.value.replace(
+      '  /**\n   * The city, town, or village of the address.',
+      `${customerAccountMailingAddressValue}  /**\n   * The city, town, or village of the address.`,
+    );
+  }
+
+  await fs.writeFile(
+    generatedDocsV2Path,
+    `${JSON.stringify(generatedDocs, null, 2)}\n`,
+  );
+};
+
 const generateExtensionsDocs = async () => {
   console.log(
     `Building Customer Account UI Extensions docs for ${EXTENSIONS_API_VERSION} version`,
@@ -98,12 +182,16 @@ const generateExtensionsDocs = async () => {
     replaceValue: '',
   });
 
+  const generatedDocsV2Path = path.join(outputDir, generatedDocsDataV2File);
+
   // Replace 'unstable' with the exact API version in relative doc links
   await replaceFileContent({
-    filePaths: path.join(outputDir, generatedDocsDataV2File),
+    filePaths: generatedDocsV2Path,
     searchValue: '/docs/api//unstable/',
     replaceValue: `/docs/api/customer-account-ui-extensions/${EXTENSIONS_API_VERSION}`,
   });
+
+  await addCustomerAccountMailingAddressDocs(generatedDocsV2Path);
 };
 
 let checkoutTempFiles = [];

packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2026-07-rc/generated_docs_data_v2.json

@@ -171,6 +171,34 @@
             }
           ]
         },
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "extendedFields",
+          "value": "AddressExtendedFields",
+          "description": "Structured address components for countries and regions that collect them. Values are `null` when the address only has flat address lines.",
+          "isOptional": true
+        },
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "addressCode",
+          "value": "string | null",
+          "description": "A country-specific address code, such as a short code or postal delivery code.",
+          "isOptional": true,
+          "examples": [
+            {
+              "title": "Example",
+              "description": "",
+              "tabs": [
+                {
+                  "code": "'01001-000'",
+                  "title": "Example"
+                }
+              ]
+            }
+          ]
+        },
         {
           "filePath": "src/surfaces/checkout/api/shared.ts",
           "syntaxKind": "PropertySignature",
@@ -352,7 +380,7 @@
           ]
         }
       ],
-      "value": "export interface MailingAddress {\n  /**\n   * The buyer's full name, typically a combination of first and last name.\n   * The value is `undefined` if the buyer didn't provide a name.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'John Doe'\n   */\n  name?: string;\n\n  /**\n   * The buyer's first name. Use this alongside `lastName` when you need to\n   * display or process name parts separately. The value is `undefined` if\n   * the buyer didn't provide a first name or the store doesn't collect\n   * split names.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'John'\n   */\n  firstName?: string;\n\n  /**\n   * The buyer's last name. Use this alongside `firstName` when you need to\n   * display or process name parts separately. The value is `undefined` if\n   * the buyer didn't provide a last name or the store doesn't collect\n   * split names.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Doe'\n   */\n  lastName?: string;\n\n  /**\n   * The buyer's company name. The value is `undefined` if the buyer didn't\n   * enter a company or the store doesn't collect company names.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Shopify'\n   */\n  company?: string;\n\n  /**\n   * The first line of the street address, including the street number and\n   * name. The value is `undefined` if the buyer hasn't entered an address yet.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example '151 O'Connor Street'\n   */\n  address1?: string;\n\n  /**\n   * The second line of the buyer's address, such as apartment number, suite,\n   * or unit. The value is `undefined` if the buyer didn't provide a second\n   * address line.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Ground floor'\n   */\n  address2?: string;\n\n  /**\n   * The city, town, or village of the address. The value is `undefined` if\n   * the buyer hasn't entered a city yet.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Ottawa'\n   */\n  city?: string;\n\n  /**\n   * The postal code or ZIP code of the address, used for mail sorting and\n   * delivery routing. The value is `undefined` if the buyer hasn't entered\n   * one yet or the country doesn't use postal codes.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'K2P 2L8'\n   */\n  zip?: string;\n\n  /**\n   * The two-letter country code in [ISO 3166 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)\n   * format. The value is `undefined` if the buyer hasn't selected a country\n   * yet.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'CA' for Canada.\n   */\n  countryCode?: CountryCode;\n\n  /**\n   * The province, state, prefecture, or region code of the address. The\n   * format varies by country. The value is `undefined` if the buyer hasn't\n   * selected one yet or the country doesn't have provinces.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'ON' for Ontario.\n   */\n  provinceCode?: string;\n\n  /**\n   * The phone number associated with the address, typically in international\n   * format. The value is `undefined` if the buyer didn't provide a phone\n   * number or the store doesn't collect phone numbers.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example '+1 613 111 2222'\n   */\n  phone?: string;\n}"
+      "value": "export interface MailingAddress {\n  /**\n   * The buyer's full name, typically a combination of first and last name.\n   * The value is `undefined` if the buyer didn't provide a name.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'John Doe'\n   */\n  name?: string;\n\n  /**\n   * The buyer's first name. Use this alongside `lastName` when you need to\n   * display or process name parts separately. The value is `undefined` if\n   * the buyer didn't provide a first name or the store doesn't collect\n   * split names.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'John'\n   */\n  firstName?: string;\n\n  /**\n   * The buyer's last name. Use this alongside `firstName` when you need to\n   * display or process name parts separately. The value is `undefined` if\n   * the buyer didn't provide a last name or the store doesn't collect\n   * split names.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Doe'\n   */\n  lastName?: string;\n\n  /**\n   * The buyer's company name. The value is `undefined` if the buyer didn't\n   * enter a company or the store doesn't collect company names.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Shopify'\n   */\n  company?: string;\n\n  /**\n   * The first line of the street address, including the street number and\n   * name. The value is `undefined` if the buyer hasn't entered an address yet.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example '151 O'Connor Street'\n   */\n  address1?: string;\n\n  /**\n   * The second line of the buyer's address, such as apartment number, suite,\n   * or unit. The value is `undefined` if the buyer didn't provide a second\n   * address line.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Ground floor'\n   */\n  address2?: string;\n\n  /**\n   * Structured address components for countries and regions that collect them.\n   * Values are `null` when the address only has flat address lines.\n   */\n  extendedFields?: AddressExtendedFields;\n\n  /**\n   * A country-specific address code, such as a short code or postal delivery code.\n   *\n   * @example '01001-000'\n   */\n  addressCode?: string | null;\n\n  /**\n   * The city, town, or village of the address. The value is `undefined` if\n   * the buyer hasn't entered a city yet.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'Ottawa'\n   */\n  city?: string;\n\n  /**\n   * The postal code or ZIP code of the address, used for mail sorting and\n   * delivery routing. The value is `undefined` if the buyer hasn't entered\n   * one yet or the country doesn't use postal codes.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'K2P 2L8'\n   */\n  zip?: string;\n\n  /**\n   * The two-letter country code in [ISO 3166 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)\n   * format. The value is `undefined` if the buyer hasn't selected a country\n   * yet.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'CA' for Canada.\n   */\n  countryCode?: CountryCode;\n\n  /**\n   * The province, state, prefecture, or region code of the address. The\n   * format varies by country. The value is `undefined` if the buyer hasn't\n   * selected one yet or the country doesn't have provinces.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example 'ON' for Ontario.\n   */\n  provinceCode?: string;\n\n  /**\n   * The phone number associated with the address, typically in international\n   * format. The value is `undefined` if the buyer didn't provide a phone\n   * number or the store doesn't collect phone numbers.\n   *\n   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).\n   *\n   * @example '+1 613 111 2222'\n   */\n  phone?: string;\n}"
     }
   },
   "CountryCode": {
@@ -8535,6 +8563,117 @@
       "isPublicDocs": true
     }
   },
+  "AddressExtendedFields": {
+    "src/surfaces/customer-account/api/shared.ts": {
+      "filePath": "src/surfaces/customer-account/api/shared.ts",
+      "name": "AddressExtendedFields",
+      "description": "Structured extended address fields for countries and regions that collect address components separately from the flat address lines.",
+      "isPublicDocs": true,
+      "members": [
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "district",
+          "value": "string | null",
+          "description": "The district or neighborhood.",
+          "isOptional": true,
+          "examples": [
+            {
+              "title": "Example",
+              "description": "",
+              "tabs": [
+                {
+                  "code": "'Bela Vista'",
+                  "title": "Example"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "line2",
+          "value": "string | null",
+          "description": "Additional address information, such as a block, floor, or unit.",
+          "isOptional": true,
+          "examples": [
+            {
+              "title": "Example",
+              "description": "",
+              "tabs": [
+                {
+                  "code": "'10th floor'",
+                  "title": "Example"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "streetName",
+          "value": "string | null",
+          "description": "The street name without the building or street number.",
+          "isOptional": true,
+          "examples": [
+            {
+              "title": "Example",
+              "description": "",
+              "tabs": [
+                {
+                  "code": "'Avenida Paulista'",
+                  "title": "Example"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "streetNumber",
+          "value": "string | null",
+          "description": "The building or street number.",
+          "isOptional": true,
+          "examples": [
+            {
+              "title": "Example",
+              "description": "",
+              "tabs": [
+                {
+                  "code": "'123'",
+                  "title": "Example"
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "filePath": "src/surfaces/customer-account/api/shared.ts",
+          "syntaxKind": "PropertySignature",
+          "name": "subdistrict",
+          "value": "string | null",
+          "description": "The subdistrict or smaller locality.",
+          "isOptional": true,
+          "examples": [
+            {
+              "title": "Example",
+              "description": "",
+              "tabs": [
+                {
+                  "code": "'Centro'",
+                  "title": "Example"
+                }
+              ]
+            }
+          ]
+        }
+      ],
+      "value": "export interface AddressExtendedFields {\n  /**\n   * The street name without the building or street number.\n   *\n   * @example 'Avenida Paulista'\n   */\n  streetName?: string | null;\n\n  /**\n   * The building or street number.\n   *\n   * @example '123'\n   */\n  streetNumber?: string | null;\n\n  /**\n   * Additional address information, such as a block, floor, or unit.\n   *\n   * @example '10th floor'\n   */\n  line2?: string | null;\n\n  /**\n   * The district or neighborhood.\n   *\n   * @example 'Bela Vista'\n   */\n  district?: string | null;\n\n  /**\n   * The subdistrict or smaller locality.\n   *\n   * @example 'Centro'\n   */\n  subdistrict?: string | null;\n}"
+    }
+  },
   "AuthenticatedAccount": {
     "src/surfaces/customer-account/api/shared.ts": {
       "filePath": "src/surfaces/customer-account/api/shared.ts",
@@ -182672,4 +182811,4 @@
       "value": "export interface UrlFieldProps extends URLFieldElementProps, UrlFieldEvents {\n}"
     }
   }
-}
+}

packages/ui-extensions/src/surfaces/customer-account/api.ts

@@ -51,6 +51,7 @@ export type {
   GraphQLError,
   SellingPlan,
   StorefrontApiVersion,
+  AddressExtendedFields,
   MailingAddress,
   ApiVersion,
   Capability,