How does a BigCommerce headless storefront resolve a page from a URL path?

Definition: A BigCommerce route lookup uses the GraphQL Storefront API route node with a URL path. The result contains the matching storefront entity, redirect details, or no result when the path matches neither an entity nor a redirect.

Key facts

• The path parameter is the only required input for the route node, according to BigCommerce's storefront routes documentation.
• A direct match can return Product, Category, Brand, NormalPage, ContactPage, RawHtmlPage, Blog, or BlogPost.
• The route node supports store 301 redirects. A redirect result is either manual or dynamic.
• IGNORE is the default redirect behavior. It prioritizes direct entity lookup and can return both a non-null redirect and a non-null node for the same path.
• BigCommerce's GraphQL Storefront API overview describes URL lookup for objects such as categories and brands and says the API can return data for multiple resources in one call.

What does the route node return for a path?

The storefront sends the path to site.route. The node field is a polymorphic result, so the query selects fields for the entity types that the application handles. BigCommerce lists products, categories, brands, several page types, blogs, and blog posts as possible node types. A path that relates to no entity or redirect produces no result from the route lookup.

This is the basic shape of a route query from BigCommerce's example, reduced to the fields that identify the matched object:

query LookUpUrl($urlPath: String!) {
  site {
    route(path: $urlPath) {
      node {
        __typename
        id
      }
      redirect {
        toUrl
      }
    }
  }
}

The __typename value lets a headless storefront select the matching fragment, while id identifies the returned object. BigCommerce's overview also describes looking up categories or brands by URL and fetching their details.

How does BigCommerce represent a redirect?

The route node supports 301 redirects added to the store. A manual redirect returns a fixed destination URL in toUrl; the storefront then makes another route query for that destination. If the destination is itself a redirect, the documentation describes a chain that requires multiple queries.

A dynamic redirect instead exposes an entity type and entity ID for an existing store resource. BigCommerce names five dynamic redirect types: ProductRedirect, BrandRedirect, BlogPostRedirect, CategoryRedirect, and PageRedirect. The target entity can be selected directly in the same route response, so the application can read the resource through the appropriate fragment.

What changes when redirectBehavior is FOLLOW?

The redirectBehavior argument accepts IGNORE and FOLLOW. Under IGNORE, which is the default, the API ignores redirects for lookup priority. If a redirect and a direct entity URL share a path, both redirect and node can contain values.

Under FOLLOW, a dynamic redirect puts its target entity in node. A manual redirect leaves node null because it has no associated entity, while redirect contains the redirect details. This distinction determines whether the storefront can render the target from the current response or must query the destination path.

BigCommerce's site-content guide applies the same route pattern to web pages, the main blog index page, and blog posts. It also states that GraphQL Storefront API queries run in the context of a particular storefront channel, so a page lookup is scoped to that channel.

Related terms

• How do BigCommerce manual and dynamic redirect targets differ?
• What does FOLLOW return for a BigCommerce GraphQL route redirect?
• How can BigCommerce redirects be written for a specific storefront site?

FAQ

What should you send to resolve a BigCommerce URL?

Send the storefront path as the path argument to site.route. BigCommerce's example uses a GraphQL variable named urlPath for that value.

What happens when you use FOLLOW for a manual redirect?

The redirect field contains the manual redirect details and node is null. Query the destination path separately to look for the destination entity.

Can you resolve a blog page with the route node?

Yes. BigCommerce documents route queries for web pages, the main blog index page, and blog posts. The returned node can expose page or blog fields selected by the query.

Sources

1. BigCommerce Docs, "Storefront Routes with the GraphQL Storefront API", Undated
2. BigCommerce Docs, "GraphQL Storefront API overview", Undated
3. BigCommerce Docs, "Site Content with the GraphQL Storefront API", Undated

---

Check how a page reads to answer engines. Open the GEO score analyzer