DEVDOCS-6492 - Document GraphQL promotion banners API usage

docs/storefront/graphql/banners.mdx

@@ -0,0 +1,71 @@
+# 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) {
+  promotionBanners(cartId: $cartId) {
+    homePage {
+      content
+    }
+    productPage {
+      content
+    }
+    cartPage {
+      content
+    }
+    checkoutPage {
+      content
+    }
+  }
+}
+```
+
+</Tab>
+<Tab>
+
+```json filename="Example response: Get all promotion banners" showLineNumbers copy
+{
+  "data": {
+    "promotionBanners": {
+      "homePage": [
+        { "content": "<div class='banner'>Welcome to our store!</div>" }
+      ],
+      "productPage": [
+        { "content": "<div class='banner'>Buy one, get one free!</div>" }
+      ],
+      "cartPage": [
+        { "content": "<div class='banner'>Don't forget your coupon!</div>" }
+      ],
+      "checkoutPage": [
+        { "content": "<div class='banner'>Free shipping on orders over $50!</div>" }
+      ]
+    }
+  }
+}
+```
+
+</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 overview](/docs/storefront/graphql)
+- [Best Practices for Using GraphQL APIs](/docs/storefront/graphql/best-practices)