How do BigCommerce manual and dynamic redirect targets differ?

Definition: In BigCommerce's GraphQL Storefront API, a manual redirect points to a fixed destination URL. A dynamic redirect identifies an existing store resource with a resource type and entity ID, so the route query can return that target entity directly.

Key facts

• BigCommerce's route node documentation says the input path can resolve to an entity, a redirect, or nothing.
• A manual redirect returns a fixed destination URL and needs a new route query to retrieve content at that URL.
• A dynamic redirect returns an entity type and entity ID. The documented GraphQL types are ProductRedirect, BrandRedirect, BlogPostRedirect, CategoryRedirect, and PageRedirect.
• With FOLLOW, a dynamic redirect can return its target entity in the node; a manual redirect leaves node null and exposes redirect details.
• BigCommerce's redirect upsert reference models to with a type, entity ID, or URL.

What is fixed in a manual redirect target?

The GraphQL route response represents a manual target as a URL. The routes documentation says that the destination URL may itself be another redirect, which can create a chain that needs multiple queries. The ManualRedirect fragment in the documented query requests the URL field:

redirect {
  toUrl
  to {
    ...on ManualRedirect {
      url
    }
  }
}

The URL is therefore the target value that the storefront application follows or queries next. It carries no resource type or entity ID for the route query to resolve directly.

How does a dynamic redirect identify its target?

The same BigCommerce documentation describes a dynamic redirect as an entity type plus the entity ID of an existing store resource. It names five GraphQL target types and says that the target can be retrieved directly within the route response. The REST redirect model uses lowercase resource values in its RedirectTo object. Its allowed values are product, brand, category, page, post, and url, with entity_id and url available as fields.

The REST response example shows a product target represented as a resource type, an entity ID, and a path:

"to": {
  "type": "product",
  "entity_id": 1,
  "url": "/new-url/"
}

This model lets an integration retain the resource identity separately from the destination URL returned in the response.

What does redirectBehavior change?

The route node accepts redirectBehavior with IGNORE as its default and FOLLOW as the other documented value. IGNORE prioritizes direct entity lookups through custom URLs. If a redirect and an entity URL share a path, both redirect and node can be non-null under that behavior.

With FOLLOW, the node contains the target entity when the redirect is dynamic. For a manual redirect, the documentation specifies a null node because the URL has no associated entity, while redirect contains the redirect details. A query can request both the redirect fields and the possible product node:

query {
  site {
    route(path: "/mug" redirectBehavior: FOLLOW) {
      redirect { __typename to { __typename ...on ProductRedirect { entityId path } } toUrl }
      node {
        id
        ... on Product { name }
      }
    }
  }
}

Which fields identify a redirect in the REST API?

The upsert endpoint accepts a list of 301RedirectUpsert objects. BigCommerce marks from_path and site_id as required and to as optional. The reference says a conflict on the pair of from_path and site_id overwrites the redirect with new data. For a fixed destination, the RedirectTo object uses the url field. For a resource target, it uses type and can include entity_id.

Related terms

• How does a BigCommerce headless storefront resolve a page from a URL path?
• What does FOLLOW return for a BigCommerce GraphQL route redirect?
• How can BigCommerce redirects be written for a specific storefront site?
• How can a BigCommerce redirect export include resolved dynamic target URLs?

FAQ

Does a manual redirect include an entity ID?

The manual GraphQL target is a fixed URL. The documented ManualRedirect query requests url, while the dynamic redirect fragments request an entity ID.

Can a dynamic redirect return the target product in one route query?

Yes. With redirectBehavior: FOLLOW, BigCommerce documents that the node returns the target entity for a dynamic redirect. The example requests a ProductRedirect entity ID and a product name field.

What is the default redirect behavior?

The default is IGNORE. Under that behavior, the API prioritizes direct entity lookups through custom URLs and can return both redirect and node when the same path has both.

Sources

1. BigCommerce, "Storefront Routes with the GraphQL Storefront API", undated
2. BigCommerce, "Upsert Redirects", undated

---

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