How can BigCommerce redirects be written for a specific storefront site?

Definition: A BigCommerce storefront redirect upsert is a PUT request whose JSON body contains redirect records. To target one storefront site, each record supplies that site's required integer site_id together with the required source path in from_path.

Key facts

• BigCommerce documents the endpoint as PUT https://api.bigcommerce.com/stores/{store_hash}/v3/storefront/redirects; its body is a list of 301RedirectUpsert objects. The Upsert Redirects reference describes the request.
• In the request schema, from_path is a required string and site_id is a required integer. The same reference says a conflict on the pair overwrites the redirect with new data.
• BigCommerce defines a site as a merchant-controlled website tied to exactly one channel. Its Multi-Storefront overview says the first Stencil storefront has site ID 1000 and is the default site. The Multi-Storefront overview explains this model.

How should the request identify the storefront site?

Put the site identifier in site_id on every redirect object. BigCommerce's Upsert Redirects reference shows this minimal request body:

[
  {
    "from_path": "/old-url/",
    "site_id": 1
  }
]

The array is significant because the endpoint expects a list, so one call can carry more than one redirect record. from_path is the source path to write, and site_id associates that path with the selected storefront site. The API reference describes the operation as upserting redirect data across all storefronts, while the required site field gives each record its site scope.

The site ID is distinct from a channel ID. BigCommerce's Multi-Storefront documentation says every site is tied to exactly one channel, while channels can exist without a site. A site also has a public-facing url and the associated channel's channel_id.

What happens when the same path is submitted again?

BigCommerce defines the conflict using both from_path and site_id. The redirect upsert schema says that submitting the same pair causes the redirect to be overwritten with new data, so the path alone is not the complete identity described by the upsert schema. A path value such as /old-url/ therefore belongs in a record with the site ID for the storefront where that redirect is managed.

The optional to object describes the destination. The reference lists product, brand, category, page, post, and url as its allowed type values, and it also documents optional entity_id and url fields. This lets the request use a BigCommerce entity or a URL as the destination while keeping from_path and site_id as the required source-side fields.

How can you find the site ID to send?

BigCommerce's Sites reference documents a site collection endpoint:

GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/sites
X-Auth-Token: {{ACCESS_TOKEN}}
Accept: application/json

The same reference says sites link headless storefronts to sales channels and shows a site response containing id, url, and channel_id. Use the returned id as the redirect request's site_id. For a default Stencil storefront, the Multi-Storefront overview identifies 1000 as the site ID, and says that site cannot be deleted.

Related terms

• How can an agency tell whether BigCommerce channel SEO settings inherit global values?
• How does a BigCommerce headless storefront resolve a page from a URL path?
• How do BigCommerce manual and dynamic redirect targets differ?

FAQ

Is site_id optional when writing a redirect?

No. BigCommerce's upsert schema marks site_id as a required integer, alongside the required from_path string. The API example includes both fields in the request object.

Does the request use a channel ID instead of a site ID?

The redirect upsert object requires site_id. BigCommerce's site documentation describes channel_id as a property of the site, while the redirect request uses the site's id in site_id.

Can one request contain several redirects?

Yes. The endpoint expects a list of 301RedirectUpsert, and the documented request body is a JSON array containing a redirect object.

Sources

1. BigCommerce, "Upsert Redirects", undated
2. BigCommerce, "Introduction to Multi-Storefront", undated
3. BigCommerce, "Sites", undated

---

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