StorefrontHeadless

Site Content with the GraphQL Storefront API

BigCommerce’s GraphQL Storefront API allows you to retrieve site content from each storefront channel. Having access to site content makes it easier to build headless storefront applications using BigCommerce’s built-in content, such as theme widgets.

Developers can use frontend GraphQL to perform the following:

  • Query web page content, including HTML pages, contact forms, blog posts, and more
  • Retrieve banner content on home, search, category, and brand pages
  • Retrieve rendered widgets built using Page Builder or the Widgets API
  • Retrieve web pages and blog posts using the web page URL

For more information on web pages, see Page Types. Queries don’t support RSS-syndicated content pages, as these are deprecated.

GraphQL Storefront API queries are made in the context of a particular storefront channel; for example, queries for web pages return only web pages for a specific storefront channel. For information on how to send requests for your storefront context, see GraphQL Storefront API Overview FAQ.

Web pages

Retrieve web pages using the following example or using a route.

When you query web pages for the default storefront channel, the response includes the main blog index page.

Use the isVisibleInNavigation field to filter for only pages that appear in the storefront’s navigation menu. Without the filter, queries also return pages that are hidden from the menu, as these pages are still accessible by URL. The filter applies to both web pages and the main index blog page.

Example query: Get web pages
query {
  site {
    content {
      pages (filters: {isVisibleInNavigation: true }) {
        edges {
          node {
            # Fields that return for all web page types 
            ... on WebPage {
              __typename
              entityId
              name
              parentEntityId
              seo {
                pageTitle
                metaKeywords
                metaDescription
              }
            }			
              
            # Fields that return for plain-text pages 
            ... on NormalPage {
              plainTextSummary (characterLimit: 100)
              path
            }
            # Fields that return for external link pages 
            ... on ExternalLinkPage {
              link
            }
            # Fields that return for contact forms 
            ... on ContactPage {
              path
              plainTextSummary (characterLimit: 100)
              contactFields
            }
            # Fields that return for raw HTML pages
            ... on RawHtmlPage {
              path
              htmlBody
            }
            # Fields that return for main blog index page
            ... on BlogIndexPage {
              path
            }
          }
        }
      }
    } 
  }
}

Rendered regions

Retrieve rendered widgets on plain-text pages. This query returns the rendered HTML content for all widgets that are placed in Regions on the given page.

Example query: Get rendered regions on plain-text pages
query {
  site {
    content {
      pages (filters: {pageType: NORMAL}) {
        edges {
          node {
            ... on NormalPage {
              path
              renderedRegions {
                regions {
                  name
                  html
                }
              }
            }
          }
        }
      }
    } 
  }
}

Blogs

Retrieve blogs using the following example or using a route.

Queries for blogs retrieve published blog posts and exclude draft blogs.

Queries return published blogs even if they are hidden from the storefront’s navigation menu, as the main blog index page and published blog posts are still accessible by URL.

Example query: Get blogs
query {
  site {
    content {
      blog {
        name
        description
        path
        posts (filters: {tags:["Most Popular", "Holiday"]}) {
          edges {
            node {
              entityId
              name
              tags
              htmlBody
              plainTextSummary (characterLimit: 100)
              author
              path
              publishedDate {
                utc
              }
              thumbnailImage {
                url (width: 100, height: 200)
                urlOriginal
                altText
                isDefault
              }
              seo {
                pageTitle
                metaKeywords
                metaDescription
              }
            }
          }
        }
      }
    }
  }
}

Routes

Retrieve web pages, the main blog index page, and blog posts using the web page URL.

The following query retrieves information for the page with the given path URL.

Example query: Get page using a route
query {
  site {
    route(path: "/blogs/") {
      node {
        id
        
        # Fields that return for plain-text pages, contact forms, and raw HTML pages
        ... on WebPage {
          entityId
          parentEntityId
          name
          isVisibleInNavigation
          seo {
            metaKeywords
            metaDescription
          }
        }
        # Fields that return for plain-text pages 
        ... on NormalPage {
          path
          plainTextSummary (characterLimit: 100)
        }
        # Fields that return for contact forms
        ... on ContactPage {
          path
          plainTextSummary (characterLimit: 100)
          contactFields
        }
        # Fields that return for raw HTML pages
        ... on RawHtmlPage {
          path
          htmlBody
        }
        # Fields that return for main blog index page
        ... on Blog {
          name
          description
          path
          isVisibleInNavigation
          posts {
            edges {
              node {
                name
                tags
              }
            }
          }
        }
        # Fields that return for blog posts
        ... on BlogPost {
          name
          tags
        }
      }
    }
  } 
}

Banners

Retrieve banners using the following example. Queries return only visible banners.

Example query: Get banners
query {
  site {
    content {
      banners {
        homePage {
          edges {
            node {
              entityId
              name
              content
              location
            }
          }
        }
        searchPage {
          edges {
            node {
              entityId
              name
              content
              location
            }
          }
        }
        categoryPage (categoryEntityId: 29) {
          edges {
            node {
              entityId
              name
              content
              location
            }
          }
        }
        brandPage (brandEntityId: 41) {
          edges {
            node {
              entityId
              name
              content
              location
            }
          }
        }
      }
    }
  }
}

Resources

Docs and reference

GraphQL Storefront API

Help Center articles