DEVDOCS-6492 - Document GraphQL promotion banners API usage

docs/storefront/graphql/banners.mdx

@@ -0,0 +1,69 @@
+# Promotion Banners with the GraphQL Storefront API
+
+BigCommerce's GraphQL Storefront API allows you to query promotional banners that can be displayed throughout the shopper journey. This includes banners for the homepage, product pages, cart, and checkout.
+
+<Callout type="warning">
+Banner content is returned as raw HTML. You must treat this content as potentially unsafe. Always sanitize or escape the HTML before rendering it to prevent cross-site scripting (XSS) vulnerabilities.
+</Callout>
+
+## Example Usage
+
+Use the `promotionBanners` query to fetch all available promotion banners for a shopper session. Pass your current cart ID if you want to fetch context-relevant banners for the cart or checkout pages.
+
+<Tabs items={['Request', 'Response']}>
+<Tab>
+
+```graphql filename="Example query: Get all promotion banners" showLineNumbers copy
+query GetPromotionBanners($cartId: String) {
+  site {
+    promotion {
+      banners(cartEntityId: $cartId) {
+        content
+        locations
+      }
+    }
+  }
+}
+```
+
+</Tab>
+<Tab>
+
+```json filename="Example response: Get all promotion banners" showLineNumbers copy
+{
+  "data": {
+    "site": {
+      "promotion": {
+        "banners": [
+          {
+            "content": "product promotion banner",
+            "locations": ["PRODUCT_PAGE"]
+          },
+          {
+            "content": "homepage promotion banner",
+            "locations": ["HOME_PAGE"]
+          },
+          {
+            "content": "promotion banner on home and product page",
+            "locations": ["HOME_PAGE", "PRODUCT_PAGE"]
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+</Tab>
+</Tabs>
+
+## Key Points
+
+- **Sanitize HTML**: Banners are delivered as raw HTML strings. Always sanitize these strings before rendering in your storefront to protect against XSS attacks.
+- **Dynamic Content**: The returned banners may change depending on the shopper’s session, cart contents, or other dynamic factors.
+- **`cartId` Parameter**: Pass the current cart ID for cart/checkout-specific banners.
+
+## Additional Resources
+- [GraphQL Storefront API Reference](/graphql-storefront/reference#group-Operations-Queries)
+- [GraphQL Storefront API overview](/docs/storefront/graphql)
+- [Best Practices for Using GraphQL APIs](/docs/storefront/graphql/best-practices)