DEVDOCS-6035: [update] geography nodes

docs/storefront/graphql/examples/index.mdx

@@ -251,3 +251,148 @@ Analytics IDs are available only after configuring the analytics service provide
 ```
 
 <a href="https://developer.bigcommerce.com/graphql-storefront/playground" target="_blank">**Try it in GraphQL Playground**</a>
+
+## Get a list of countries
+
+The `geography` node provides a list of all supported shipping countries and their corresponding states or provinces. By default, the full list is returned unless you apply a filter. To narrow down the list, you can use the **Settings** > **Shipping** >  **Checkout shipping options** filter in the control panel. This filter limits the results to only those countries included in your active shipping zones.
+
+The `geography` node currently supports two filters, both available on the level of `countries`: `code` and `name`. These require exact matches to the country's two-letter country code and full name, respectively.
+
+<Tabs  items={[`Geography Node`, `Geography Response`, `Shipping Settings`, `Shipping Response`]}>
+<Tab>
+
+```graphql filename="Example query: Get list of countries via geography" showLineNumbers copy
+ {
+  geography {
+    countries {
+      entityId
+      code
+      name
+      statesOrProvinces {
+        entityId
+        name
+        abbreviation
+      }
+    }
+  }
+}
+```
+</Tab>
+
+<Tab>
+**Note:** The example below shows the structure of the response, but omits most of the data.
+
+```json filename="Example response: Get list of countries via geography" showLineNumbers copy
+{
+  "data": {
+    "geography": {
+      "countries": [
+        {
+          "entityId": 1,
+          "code": "AF",
+          "name": "Afghanistan",
+          "statesOrProvinces": []
+        },
+        {
+          "entityId": 10,
+          "code": "AR",
+          "name": "Argentina",
+          "statesOrProvinces": [
+            {
+              "entityId": 309,
+              "name": "Ciudad Autónoma de Buenos Aires",
+              "abbreviation": "C"
+            },
+            {
+              "entityId": 310,
+              "name": "Buenos Aires",
+              "abbreviation": "B"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+
+```
+</Tab>
+
+<Tab>
+**Note:** The node `site.settings.shipping.supportedShippingDestinations` follows the same general schema as the `geography` node, but it is implicitly filtered based on store settings.
+
+```graphql filename="Example query: Get list of countries via shipping" showLineNumbers copy
+ {
+  site {
+    settings {
+      shipping {
+        supportedShippingDestinations {
+          countries {
+            entityId
+            code
+            name
+            statesOrProvinces {
+              entityId
+              name
+              abbreviation
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+</Tab>
+
+<Tab>
+**Note:** The example below shows the structure of the response. Your store's response will vary based on your shipping settings.
+
+```json filename="Example query: Get list of countries via shipping" showLineNumbers copy
+{
+  "data": {
+    "site": {
+      "settings": {
+        "shipping": {
+          "supportedShippingDestinations": {
+            "countries": [
+              {
+                "entityId": 13,
+                "code": "AU",
+                "name": "Australia",
+                "statesOrProvinces": [
+                  {
+                    "entityId": 208,
+                    "name": "Australian Capital Territory",
+                    "abbreviation": "ACT"
+                  },
+                  {
+                    "entityId": 209,
+                    "name": "New South Wales",
+                    "abbreviation": "NSW"
+                  }
+                 ]
+              },
+              {
+                "entityId": 38,
+                "code": "CA",
+                "name": "Canada",
+                "statesOrProvinces": [
+                  {
+                    "entityId": 78,
+                    "name": "Yukon Territory",
+                    "abbreviation": "YT"
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+</Tab>
+</Tabs>
+<a href="https://developer.bigcommerce.com/graphql-storefront/playground" target="_blank">**Try it in GraphQL Playground**</a>