feat: Add out-of-stock/backorder message to product lists

Tharaae · Tharaae · commit 21fa78493dfe · 2025-12-02T16:42:20.000+11:00
diff --git a/.changeset/tricky-plants-teach.md b/.changeset/tricky-plants-teach.md
@@ -0,0 +1,21 @@
+---
+"@bigcommerce/catalyst-core": minor
+---
+
+Add out-of-stock / backorder message to product cards on PLPs based on store settings:
+- Add out of stock message if the product is out of stock and stock is set to display it.
+- Add the backorder message if the product has no on-hand stock and is available for backorder and the store/product is set to display the backorder message
+
+## Migration
+For existing Catalyst stores, to get the newly added feature, simply rebase the existing code with the new release code. The files to be rebased for this change to be applied are:
+- core/app/[locale]/(default)/(faceted)/brand/[slug]/page-data.ts
+- core/app/[locale]/(default)/(faceted)/brand/[slug]/page.tsx
+- core/app/[locale]/(default)/(faceted)/category/[slug]/page-data.ts
+- core/app/[locale]/(default)/(faceted)/category/[slug]/page.tsx
+- core/app/[locale]/(default)/(faceted)/search/page-data.ts
+- core/app/[locale]/(default)/(faceted)/search/page.tsx
+- core/app/[locale]/(default)/page-data.ts
+- core/app/[locale]/(default)/page.tsx
+- core/components/product-card/fragment.ts
+- core/data-transformers/product-card-transformer.ts
+- core/vibes/soul/primitives/product-card/index.tsx
diff --git a/core/app/[locale]/(default)/(faceted)/brand/[slug]/page-data.ts b/core/app/[locale]/(default)/(faceted)/brand/[slug]/page-data.ts
@@ -16,6 +16,11 @@ const BrandPageQuery = graphql(`
         }
       }
       settings {
+        inventory {
+          defaultOutOfStockMessage
+          showOutOfStockMessage
+          showBackorderMessage
+        }
         storefront {
           catalog {
             productComparisonsEnabled
diff --git a/core/app/[locale]/(default)/(faceted)/brand/[slug]/page.tsx b/core/app/[locale]/(default)/(faceted)/brand/[slug]/page.tsx
@@ -11,7 +11,7 @@ import { getFilterParsers } from '@/vibes/soul/sections/products-list-section/fi
 import { getSessionCustomerAccessToken } from '~/auth';
 import { facetsTransformer } from '~/data-transformers/facets-transformer';
 import { pageInfoTransformer } from '~/data-transformers/page-info-transformer';
-import { pricesTransformer } from '~/data-transformers/prices-transformer';
+import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
 
 import { MAX_COMPARE_LIMIT } from '../../../compare/page-data';
@@ -132,16 +132,15 @@ export default async function Brand(props: Props) {
     const search = await streamableFacetedSearch;
     const products = search.products.items;
 
-    return products.map((product) => ({
-      id: product.entityId.toString(),
-      title: product.name,
-      href: product.path,
-      image: product.defaultImage
-        ? { src: product.defaultImage.url, alt: product.defaultImage.altText }
-        : undefined,
-      price: pricesTransformer(product.prices, format),
-      subtitle: product.brand?.name ?? undefined,
-    }));
+    const { defaultOutOfStockMessage, showOutOfStockMessage, showBackorderMessage } =
+      settings?.inventory || {};
+
+    return productCardTransformer(
+      products,
+      format,
+      showOutOfStockMessage ? defaultOutOfStockMessage : undefined,
+      showBackorderMessage,
+    );
   });
 
   const streamableTotalCount = Streamable.from(async () => {
diff --git a/core/app/[locale]/(default)/(faceted)/category/[slug]/page-data.ts b/core/app/[locale]/(default)/(faceted)/category/[slug]/page-data.ts
@@ -35,6 +35,11 @@ const CategoryPageQuery = graphql(
           }
         }
         settings {
+          inventory {
+            defaultOutOfStockMessage
+            showOutOfStockMessage
+            showBackorderMessage
+          }
           storefront {
             catalog {
               productComparisonsEnabled
diff --git a/core/app/[locale]/(default)/(faceted)/category/[slug]/page.tsx b/core/app/[locale]/(default)/(faceted)/category/[slug]/page.tsx
@@ -12,7 +12,7 @@ import { getFilterParsers } from '@/vibes/soul/sections/products-list-section/fi
 import { getSessionCustomerAccessToken } from '~/auth';
 import { facetsTransformer } from '~/data-transformers/facets-transformer';
 import { pageInfoTransformer } from '~/data-transformers/page-info-transformer';
-import { pricesTransformer } from '~/data-transformers/prices-transformer';
+import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
 
 import { MAX_COMPARE_LIMIT } from '../../../compare/page-data';
@@ -145,16 +145,15 @@ export default async function Category(props: Props) {
     const search = await streamableFacetedSearch;
     const products = search.products.items;
 
-    return products.map((product) => ({
-      id: product.entityId.toString(),
-      title: product.name,
-      href: product.path,
-      image: product.defaultImage
-        ? { src: product.defaultImage.url, alt: product.defaultImage.altText }
-        : undefined,
-      price: pricesTransformer(product.prices, format),
-      subtitle: product.brand?.name ?? undefined,
-    }));
+    const { defaultOutOfStockMessage, showOutOfStockMessage, showBackorderMessage } =
+      settings?.inventory || {};
+
+    return productCardTransformer(
+      products,
+      format,
+      showOutOfStockMessage ? defaultOutOfStockMessage : undefined,
+      showBackorderMessage,
+    );
   });
 
   const streamableTotalCount = Streamable.from(async () => {
diff --git a/core/app/[locale]/(default)/(faceted)/search/page-data.ts b/core/app/[locale]/(default)/(faceted)/search/page-data.ts
@@ -8,6 +8,11 @@ const SearchPageQuery = graphql(`
   query SearchPageQuery {
     site {
       settings {
+        inventory {
+          defaultOutOfStockMessage
+          showOutOfStockMessage
+          showBackorderMessage
+        }
         storefront {
           catalog {
             productComparisonsEnabled
diff --git a/core/app/[locale]/(default)/(faceted)/search/page.tsx b/core/app/[locale]/(default)/(faceted)/search/page.tsx
@@ -10,7 +10,7 @@ import { getFilterParsers } from '@/vibes/soul/sections/products-list-section/fi
 import { getSessionCustomerAccessToken } from '~/auth';
 import { facetsTransformer } from '~/data-transformers/facets-transformer';
 import { pageInfoTransformer } from '~/data-transformers/page-info-transformer';
-import { pricesTransformer } from '~/data-transformers/prices-transformer';
+import { productCardTransformer } from '~/data-transformers/product-card-transformer';
 import { getPreferredCurrencyCode } from '~/lib/currency';
 
 import { MAX_COMPARE_LIMIT } from '../../compare/page-data';
@@ -117,16 +117,15 @@ export default async function Search(props: Props) {
     const search = await streamableFacetedSearch;
     const products = search.products.items;
 
-    return products.map((product) => ({
-      id: product.entityId.toString(),
-      title: product.name,
-      href: product.path,
-      image: product.defaultImage
-        ? { src: product.defaultImage.url, alt: product.defaultImage.altText }
-        : undefined,
-      price: pricesTransformer(product.prices, format),
-      subtitle: product.brand?.name ?? undefined,
-    }));
+    const { defaultOutOfStockMessage, showOutOfStockMessage, showBackorderMessage } =
+      settings?.inventory || {};
+
+    return productCardTransformer(
+      products,
+      format,
+      showOutOfStockMessage ? defaultOutOfStockMessage : undefined,
+      showBackorderMessage,
+    );
   });
 
   const streamableTitle = Streamable.from(async () => {
diff --git a/core/app/[locale]/(default)/page-data.ts b/core/app/[locale]/(default)/page-data.ts
@@ -61,6 +61,13 @@ const HomePageQuery = graphql(
             }
           }
         }
+        settings {
+          inventory {
+            defaultOutOfStockMessage
+            showOutOfStockMessage
+            showBackorderMessage
+          }
+        }
       }
     }
   `,
diff --git a/core/app/[locale]/(default)/page.tsx b/core/app/[locale]/(default)/page.tsx
@@ -36,15 +36,31 @@ export default async function Home({ params }: Props) {
 
     const featuredProducts = removeEdgesAndNodes(data.site.featuredProducts);
 
-    return productCardTransformer(featuredProducts, format);
+    const { defaultOutOfStockMessage, showOutOfStockMessage, showBackorderMessage } =
+      data.site.settings?.inventory || {};
+
+    return productCardTransformer(
+      featuredProducts,
+      format,
+      showOutOfStockMessage ? defaultOutOfStockMessage : undefined,
+      showBackorderMessage,
+    );
   });
 
   const streamableNewestProducts = Streamable.from(async () => {
     const data = await streamablePageData;
 
     const newestProducts = removeEdgesAndNodes(data.site.newestProducts);
 
-    return productCardTransformer(newestProducts, format);
+    const { defaultOutOfStockMessage, showOutOfStockMessage, showBackorderMessage } =
+      data.site.settings?.inventory || {};
+
+    return productCardTransformer(
+      newestProducts,
+      format,
+      showOutOfStockMessage ? defaultOutOfStockMessage : undefined,
+      showBackorderMessage,
+    );
   });
 
   return (
diff --git a/core/components/product-card/fragment.ts b/core/components/product-card/fragment.ts
@@ -1,6 +1,8 @@
 import { PricingFragment } from '~/client/fragments/pricing';
 import { graphql } from '~/client/graphql';
 
+import { ProductVariantsInventoryFragment } from '../product-variants-inventory/fragment';
+
 export const ProductCardFragment = graphql(
   `
     fragment ProductCardFragment on Product {
@@ -15,12 +17,21 @@ export const ProductCardFragment = graphql(
         name
         path
       }
+      inventory {
+        hasVariantInventory
+        isInStock
+        aggregated {
+          availableForBackorder
+          unlimitedBackorder
+        }
+      }
       reviewSummary {
         numberOfReviews
         averageRating
       }
       ...PricingFragment
+      ...ProductVariantsInventoryFragment
     }
   `,
-  [PricingFragment],
+  [PricingFragment, ProductVariantsInventoryFragment],
 );
diff --git a/core/components/product-variants-inventory/fragment.ts b/core/components/product-variants-inventory/fragment.ts
@@ -0,0 +1,24 @@
+import { graphql } from '~/client/graphql';
+
+export const ProductVariantsInventoryFragment = graphql(`
+  fragment ProductVariantsInventoryFragment on Product {
+    variants {
+      edges {
+        node {
+          entityId
+          sku
+          inventory {
+            byLocation {
+              edges {
+                node {
+                  locationEntityId
+                  backorderMessage
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`);
diff --git a/core/data-transformers/product-card-transformer.ts b/core/data-transformers/product-card-transformer.ts
@@ -1,3 +1,4 @@
+import { removeEdgesAndNodes } from '@bigcommerce/catalyst-client';
 import { ResultOf } from 'gql.tada';
 import { getFormatter } from 'next-intl/server';
 
@@ -7,9 +8,43 @@ import { ProductCardFragment } from '~/components/product-card/fragment';
 
 import { pricesTransformer } from './prices-transformer';
 
+const getInventoryMessage = (
+  product: ResultOf<typeof ProductCardFragment>,
+  outOfStockMessage?: string,
+  showBackorderMessage?: boolean,
+) => {
+  if (!product.inventory.isInStock) {
+    return outOfStockMessage;
+  }
+
+  if (!showBackorderMessage || product.inventory.hasVariantInventory) {
+    return undefined;
+  }
+
+  const { availableForBackorder, unlimitedBackorder } = product.inventory.aggregated || {};
+
+  const hasBackorderAvailablity = !!availableForBackorder || unlimitedBackorder;
+
+  if (!hasBackorderAvailablity) {
+    return undefined;
+  }
+
+  const baseVariant = removeEdgesAndNodes(product.variants).at(0);
+
+  if (!baseVariant?.inventory?.byLocation) {
+    return undefined;
+  }
+
+  const inventoryByLocation = removeEdgesAndNodes(baseVariant.inventory.byLocation).at(0);
+
+  return inventoryByLocation?.backorderMessage || undefined;
+};
+
 export const singleProductCardTransformer = (
   product: ResultOf<typeof ProductCardFragment>,
   format: ExistingResultType<typeof getFormatter>,
+  outOfStockMessage?: string,
+  showBackorderMessage?: boolean,
 ): Product => {
   return {
     id: product.entityId.toString(),
@@ -21,12 +56,17 @@ export const singleProductCardTransformer = (
     price: pricesTransformer(product.prices, format),
     subtitle: product.brand?.name ?? undefined,
     rating: product.reviewSummary.averageRating,
+    inventoryMessage: getInventoryMessage(product, outOfStockMessage, showBackorderMessage),
   };
 };
 
 export const productCardTransformer = (
   products: Array<ResultOf<typeof ProductCardFragment>>,
   format: ExistingResultType<typeof getFormatter>,
+  outOfStockMessage?: string,
+  showBackorderMessage?: boolean,
 ): Product[] => {
-  return products.map((product) => singleProductCardTransformer(product, format));
+  return products.map((product) =>
+    singleProductCardTransformer(product, format, outOfStockMessage, showBackorderMessage),
+  );
 };
diff --git a/core/vibes/soul/primitives/product-card/index.tsx b/core/vibes/soul/primitives/product-card/index.tsx

Original file line number	Diff line number	Diff line change
@@ -16,6 +16,11 @@ const BrandPageQuery = graphql(`
`16`	`16`	`}`
`17`	`17`	`}`
`18`	`18`	`settings {`
	`19`	`+ inventory {`
	`20`	`+ defaultOutOfStockMessage`
	`21`	`+ showOutOfStockMessage`
	`22`	`+ showBackorderMessage`
	`23`	`+ }`
`19`	`24`	`storefront {`
`20`	`25`	`catalog {`
`21`	`26`	`productComparisonsEnabled`
Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,11 @@ const CategoryPageQuery = graphql(`
`35`	`35`	`}`
`36`	`36`	`}`
`37`	`37`	`settings {`
	`38`	`+ inventory {`
	`39`	`+ defaultOutOfStockMessage`
	`40`	`+ showOutOfStockMessage`
	`41`	`+ showBackorderMessage`
	`42`	`+ }`
`38`	`43`	`storefront {`
`39`	`44`	`catalog {`
`40`	`45`	`productComparisonsEnabled`
Original file line number	Diff line number	Diff line change
`@@ -61,6 +61,13 @@ const HomePageQuery = graphql(`
`61`	`61`	`}`
`62`	`62`	`}`
`63`	`63`	`}`
	`64`	`+ settings {`
	`65`	`+ inventory {`
	`66`	`+ defaultOutOfStockMessage`
	`67`	`+ showOutOfStockMessage`
	`68`	`+ showBackorderMessage`
	`69`	`+ }`
	`70`	`+ }`
`64`	`71`	`}`
`65`	`72`	`}`
`66`	`73`	`,