Storefront Routes with the GraphQL Storefront API

The BigCommerce GraphQL Storefront API allows you to find the destination entity of a route (URL) for each storefront channel using the route node. This option makes it easier to build headless storefront applications, removing the need to track entity ID and type when accessing data for entities such as Products, Categories, Pages, Blogs, and more.

The destination URL is the only required input when using the route node. You will provide an input with the path parameter on the route node. The response will be an entity at that URL, a redirect to a new location, or nothing if the URL does not relate to an entity or redirect.

When querying a route, the response may include the following node types:

• Product
• Category
• Brand
• NormalPage
• ContactPage
• RawHtmlPage
• Blog
• BlogPost

Redirect support

The route node supports 301 Redirects that you have added to the store. If the URL provided as input to the route references a redirect, then the response will return a Redirect node which comes in two varieties: a manual redirect or a dynamic redirect.

A ManualRedirect returns a fixed destination URL. You will need a new route query to attempt to pull the content at that destination URL. If the destination URL itself is a redirect, this can create a chain of redirects requiring multiple queries.

A “dynamic redirect” returns an entity type and entity ID of an existing store resource. There are five types of dynamic redirects: ProductRedirect, BrandRedirect, BlogPostRedirect, CategoryRedirect, and PageRedirect. Once the entity type and ID are retrieved, you can initiate a new query to pull that content from the appropriate resource node. With dynamic redirects, you can retrieve the target entity directly within the route query response, avoiding an additional request. This is detailed below.

Redirect behavior of route node

It is possible to supply a redirectBehavior input argument to the route node which supports two values:

• IGNORE(default):

  • The API ignores redirects and prioritizes direct entity lookups via custom URLs.
  • If both a redirect and an entity URL exist for the same path, both the redirect and node nodes return non-null values.
  • This behavior ensures backward compatibility.

• FOLLOW:

  • The node node returns the target entity (e.g., category, product, blog, etc.) if the redirect is dynamic.
  • For static/manual redirects, the node node returns null (since there’s no associated entity), while the redirect node provides the redirect details.

Example queries

Query: Fetching route details

This example retrieves details about an object (e.g., Product, Brand, or Category) based on a given URL path.

1
 query LookUpUrl(
2
   $urlPath: String!
3
   # Use GraphQL Query Variables to provide a path
4
 ) {
5
   site {
6
     route(path: $urlPath) {
7
       node {
8
         __typename
9
         id
10
         # A different response is returned based on which type of object was matched
11
         ... on Category {
12
           name
13
           description
14
         }
15
         ... on Brand {
16
           name
17
           defaultImage {
18
             url(width: 200)
19
           }
20
         }
21
         ... on Product {
22
           name
23
           description
24
           images {
25
             edges {
26
               node {
27
                 url(width: 500, height: 500)
28
               }
29
             }
30
           }
31
         }
32
        }
33
         redirect {
34
           toUrl
35
           to {
36
             ...on ProductRedirect {
37
              path
38
              entityId
39
           }
40
             ...on ManualRedirect {
41
              url
42
          }
43
        }
44
      }
45
    }
46
  }
47
}

    {
      "urlPath": "/Blouse/"
    }

Query: Using IGNORE redirect behavior

In this example query, the node value is “null” because the redirect is ignored. The response is a redirect node because the input path of “/mug” is associated with a 301 redirect in the store. Note that the redirect behavior: IGNORE input is the default, so you can exclude it from the query and receive the same results.

1
 query {
2
   site {
3
      route(path: "/mug" redirectBehavior: IGNORE) {
4
        redirect {__typename to {__typename ...on ProductRedirect{entityId path}} toUrl} 
5
        node {
6
          id
7
          ... on Product {
8
            name
9
            }
10
           }
11
          }
12
        }
13
      }

Query: Using FOLLOW redirect behavior

In this example, the node returns the entity targeted by the dynamic redirect as part of the response because we chose to FOLLOW the redirect.

1
 query {
2
   site {
3
      route(path: "/mug" redirectBehavior: FOLLOW) {
4
        redirect {__typename to {__typename ...on ProductRedirect{entityId path}} toUrl} 
5
        node {
6
          id
7
          ... on Product {
8
            name
9
            }
10
           }
11
          }
12
        }
13
      }