From 55e5b4c0ad0c8730743a264cfaa97ffca0402197 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Wed, 1 Oct 2025 12:23:59 -0600 Subject: [PATCH 1/3] DEVDOCS-6492 - Document GraphQL promotion banners API usage Added documentation for querying promotional banners using the GraphQL Storefront API, including example queries and responses. --- docs/storefront/graphql/banners.mdx | 71 +++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/storefront/graphql/banners.mdx diff --git a/docs/storefront/graphql/banners.mdx b/docs/storefront/graphql/banners.mdx new file mode 100644 index 000000000..f374c3016 --- /dev/null +++ b/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. + + +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. + + +## 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. + + + + +```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 + } + } +} +``` + + + + +```json filename="Example response: Get all promotion banners" showLineNumbers copy +{ + "data": { + "promotionBanners": { + "homePage": [ + { "content": "" } + ], + "productPage": [ + { "content": "" } + ], + "cartPage": [ + { "content": "" } + ], + "checkoutPage": [ + { "content": "" } + ] + } + } +} +``` + + + + +## 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) From 79e8cd2a8b5263f70bd582ddf1817661e5a29fb3 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Tue, 14 Oct 2025 08:59:44 -0600 Subject: [PATCH 2/3] Update docs/storefront/graphql/banners.mdx --- docs/storefront/graphql/banners.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/storefront/graphql/banners.mdx b/docs/storefront/graphql/banners.mdx index f374c3016..8ae7468a5 100644 --- a/docs/storefront/graphql/banners.mdx +++ b/docs/storefront/graphql/banners.mdx @@ -66,6 +66,6 @@ query GetPromotionBanners($cartId: String) { - **`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) From d00671b98f55b3740e5162e372fcff6aef475fb3 Mon Sep 17 00:00:00 2001 From: Terra Hyde Date: Tue, 14 Oct 2025 10:15:54 -0600 Subject: [PATCH 3/3] Datatypes were updated **NOTE:** Promotion type is hidden behind a feature flag currently, though it is deployed - updated query to match the structure indicated in `bigcommerce/storefront` - confirmed new query against schema files --- docs/storefront/graphql/banners.mdx | 48 ++++++++++++++--------------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/storefront/graphql/banners.mdx b/docs/storefront/graphql/banners.mdx index 8ae7468a5..13893d249 100644 --- a/docs/storefront/graphql/banners.mdx +++ b/docs/storefront/graphql/banners.mdx @@ -15,18 +15,12 @@ Use the `promotionBanners` query to fetch all available promotion banners for a ```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 + site { + promotion { + banners(cartEntityId: $cartId) { + content + locations + } } } } @@ -38,19 +32,23 @@ query GetPromotionBanners($cartId: String) { ```json filename="Example response: Get all promotion banners" showLineNumbers copy { "data": { - "promotionBanners": { - "homePage": [ - { "content": "" } - ], - "productPage": [ - { "content": "" } - ], - "cartPage": [ - { "content": "" } - ], - "checkoutPage": [ - { "content": "" } - ] + "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"] + } + ] + } } } }