Blog Ecommerce March 7, 2026 7 min read

BigCommerce Catalog Image Fallbacks for Missing Products

Handle missing BigCommerce product thumbnail URLs in Stencil themes and headless storefronts using onerror handlers and generated fallback URLs.

BigCommerce product image placeholderBigCommerce StencilHeadless BigCommerceEcommerce image fallbackProduct catalog

BigCommerce Catalog Image Fallbacks for Missing Products

BigCommerce products can be created without images. The Catalog API returns a `thumbnail_url` field that is an empty string or contains a path to the BigCommerce default gray square when no image has been uploaded. That default image is low-resolution, does not match your store's branding, and is the same for every product.

Replacing missing thumbnails with generated, brand-consistent fallback URLs requires a small check in either the Stencil template layer or your headless storefront component. fallback.pics generates placeholder images from URL parameters with no upload or storage required.

BigCommerce image fields

What BigCommerce returns for products without images

The BigCommerce Catalog V2 and V3 REST APIs return image data on product objects. In V3, the primary image is under `images` — an array that is empty when no images have been uploaded. The `thumbnail_url` shortcut field on a product returns BigCommerce's default gray square image hosted at `cdn11.bigcommerce.com/s-{hash}/images/stencil/default-bc-image.jpg`.

The default image is 1280×1280 but visually identical across every product. Storefront buyers cannot distinguish one missing-image product from another. In a product grid with multiple missing images, every card looks the same, which is confusing.

The Storefront GraphQL API returns `defaultImage: { url: string } | null` on the Product type. A null value here — rather than the default image URL — indicates no image has ever been uploaded. Both patterns require a fallback strategy.

Stencil templates

Handlebars fallback in Stencil themes

BigCommerce Stencil themes use Handlebars. Product image data is available in the `product.main_image` and `product.images` template variables. When `product.main_image` is empty, apply a fallback URL.

The Handlebars `{{#if}}` block is the right tool. Check `product.main_image` before rendering the img tag and output the fallback src in the `{{else}}` branch.

Implementation text

{{! templates/components/products/card.html }}
{{#if product.main_image}}
  <img
    src="{{getImageSrcset product.main_image use_default_sizes=true}}"
    alt="{{product.main_image.alt}}"
    width="300"
    height="300"
  />
{{else}}
  <img
    src="https://fallback.pics/api/v1/300x300?text={{product.name}}"
    alt="{{product.name}}"
    width="300"
    height="300"
  />
{{/if}}

Headless storefront

Null checks in a React or Next.js headless storefront

Headless BigCommerce storefronts commonly use the Storefront GraphQL API or the Catalyst framework. The GraphQL Product type returns `defaultImage` as a nullable object. A null check before accessing `defaultImage.url` is the minimum needed to avoid a runtime crash.

Write a utility function that accepts the product data and returns a valid image URL or a generated fallback. This function should handle both the null case and the BigCommerce default image case if you want to replace the gray square.

Implementation tsx

const BC_DEFAULT_IMAGE = 'cdn11.bigcommerce.com';

function productImageUrl(
  product: BigCommerceProduct,
  width = 400,
  height = 400,
): string {
  const url = product.defaultImage?.url ?? product.images?.[0]?.url;
  // Replace the BigCommerce default gray square with a branded fallback
  if (!url || url.includes(BC_DEFAULT_IMAGE)) {
    const name = encodeURIComponent(product.name);
    return `https://fallback.pics/api/v1/${width}x${height}?text=${name}`;
  }
  return url;
}

Cart and checkout

Line item thumbnail fallbacks

Cart line items in BigCommerce also reference product images. When a product has no image, the cart thumbnail column shows the default gray square or breaks. The Cart API returns `imageUrl` on each line item — apply the same fallback check.

Cart and checkout are high-trust surfaces. A broken or visually confusing image at checkout can increase cart abandonment. A labeled placeholder — even a simple one — is less disruptive than a generic gray box or a broken icon.

Implementation tsx

// Cart line item with fallback
function cartItemImageUrl(item: BigCommerceCartItem): string {
  const url = item.imageUrl;
  if (!url || url.includes(BC_DEFAULT_IMAGE)) {
    return `https://fallback.pics/api/v1/square/80?text=${encodeURIComponent(item.name)}`;
  }
  return url;
}

Search results

Product search and faceted results with missing thumbnails

BigCommerce search results (via Elasticsearch-backed APIs) return the same thumbnail data as the catalog API. If a merchant runs a search campaign while mid-import, search result pages may contain products without images. Applying the same fallback utility to search results keeps the results page consistent with the main catalog.

Search result pages are often conversion-critical. Products that appear visually broken or that look identical to every other missing-image product in search results perform worse in click-through. A labeled placeholder that shows the product name is meaningfully better.

Resources

What to standardize before shipping

BigCommerce returns its own default gray square for products without images — detect it by hostname and replace with a branded fallback.
In Stencil themes, use the Handlebars {{#if product.main_image}} block to conditionally output the fallback src.
In headless storefronts, check defaultImage against null and the BigCommerce default hostname before using the URL.
Apply the same fallback logic to cart line item thumbnails — checkout is a high-trust surface where broken images increase abandonment.
Use the product name as the fallback text parameter so each missing-image card remains identifiable in search results and grids.

Production fallback layer