> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Checkout Domains > Configure the checkout URL for a Catalyst channel on Storefront Hosting with the Catalyst CLI, including the same-domain requirement and the checkout hostname BigCommerce provisions for auto-generated hostnames. Checkout is always hosted by BigCommerce, never by your Catalyst application. When a shopper starts checkout, your storefront asks BigCommerce for a single-use redirect URL and sends them to it — so the domain checkout runs on is a property of the channel, not of your code. This page covers putting checkout on the same domain as your storefront with the Catalyst CLI, whether the storefront is on an auto-generated hostname or on your own domain. > **Warning** > > The Catalyst CLI is generally available, but Storefront Hosting is currently > in closed beta. There may be breaking changes to the Storefront Hosting APIs as we > finalize them. To express interest in gaining access, fill out the [Storefront Hosting Closed Beta Interest Form](https://docs.google.com/forms/d/e/1FAIpQLSfDepq3qRtEtavb1wQvSvdK21pwr_kNsYQbH2B7JjWYyptUSA/viewform?usp=header). ## Why the checkout domain matters Because your storefront and checkout are served by different systems, they can end up on different domains. When they do, browsers that restrict cross-domain cookies — Safari with Intelligent Tracking Prevention, and Chrome's privacy controls — may not carry the shopper's session and cart from one to the other. BigCommerce enforces a rule that prevents this: **the checkout URL must share a main domain with the channel's storefront URL.** A storefront on `www.example.com` can use `checkout.example.com`, but not `checkout.example.org`. Setting a checkout URL that breaks the rule returns an error explaining it. A channel that has no checkout URL of its own falls back to a shared checkout domain — the primary URL of the store's *default* channel, which is usually a `mybigcommerce.com` hostname. That fallback works, but it is almost always a different domain than your storefront. It is also easy to miss: changing a channel's site URL doesn't move its checkout URL to the new domain. BigCommerce removes a channel's custom checkout URL whenever its site URL changes, so checkout falls back to the shared domain until you set a checkout URL again. After any site URL change, re-check checkout with `channels info`. ## Prerequisites * The channel's site URL pointing at your storefront, either its auto-generated hostname or a custom domain. See [`channels update`](/developer/docs/storefront/catalyst/reference/cli#channels-update). BigCommerce checks the same-domain rule against this URL, so set it before the checkout URL. * Store credentials available to the CLI, either from `pnpm catalyst auth login` or through `--store-hash` and `--access-token`. See [Authentication](/developer/docs/storefront/catalyst/deployment/storefront-hosting/overview#authentication). ## Check the current configuration Run `channels info` to see where a channel's storefront and checkout currently point: ```shell showLineNumbers={false} pnpm catalyst channels info --channel-id 123 ``` ```text ✔ Channel 123: Storefront https://www.example.com Canonical https://store-abc123-123.mybigcommerce.com Checkout https://checkout.example.com ``` The three URLs are distinct and easy to confuse: | URL type | What it is | | :--------- | :----------------------------------------------------------------------- | | Storefront | The shopper-facing domain your Catalyst application is served from. | | Canonical | BigCommerce's own permanent address for the channel. Not shopper-facing. | | Checkout | The domain BigCommerce serves hosted checkout from for this channel. | Here, the storefront is on a custom domain, but the channel has no checkout URL of its own. The command says so and warns that checkout is on a different domain than the storefront: ```text ℹ This channel has no checkout URL of its own, so checkout uses the default channel's primary URL. ⚠ Checkout is on the default channel's domain (store-abc123-1.mybigcommerce.com), not this channel's storefront (www.example.com). ℹ Shopper sessions and carts may not carry into checkout in browsers that restrict cross-domain cookies. ℹ To put checkout on this channel's own domain, point checkout.example.com at BigCommerce and provision a certificate for it there. ``` A channel doesn't start this way when you create it with [One-Click Catalyst](/developer/docs/storefront/catalyst/getting-started/one-click-catalyst). It starts with its preview URL as the storefront and its own checkout URL on the same preview domain: ```text showLineNumbers={false} Storefront https://store-{store_hash}-{channel_id}.catalyst-sandbox-vercel.store Checkout https://store-{store_hash}-{channel_id}.c.catalyst-sandbox-vercel.store ``` You see the warning above when a channel was created without a checkout URL, for example [through the API](/developer/docs/storefront/catalyst/guides/manually-create-catalyst-channel), or when a storefront URL change removed it. Either way, give the channel a checkout URL of its own on the storefront's domain before production. A channel that *does* have its own checkout URL, but on a domain that no longer matches the storefront, gets a different warning — that usually means a storefront URL change left the checkout URL behind: ```text ⚠ This channel's checkout URL (checkout.old-domain.com) is on a different domain than its storefront (www.example.com) — most likely a storefront URL change left it behind. ℹ Shopper sessions and carts may not carry into checkout in browsers that restrict cross-domain cookies. ``` ## Auto-generated hostnames A project that has not been given a custom domain is served from an auto-generated hostname in the form `.catalyst-sandbox.store`. Its checkout hostname is the same hostname with a `c.` prefix: ```text showLineNumbers={false} Storefront https://.catalyst-sandbox.store Checkout https://c..catalyst-sandbox.store ``` There is nothing to set up beforehand. Setting `c..catalyst-sandbox.store` as the channel's checkout URL is what provisions it: BigCommerce creates its DNS record and issues its certificate in response. The certificate usually takes a minute or two, and checkout fails on that hostname until it has one. The easiest way to set it is to accept the prompt after a deploy (see [Set it during a deploy](#set-it-during-a-deploy)). The CLI sets the checkout URL, waits for the certificate, and confirms when checkout is being served: ```text ✔ Updated channel 123 checkout URL to https://c.my-project.catalyst-sandbox.store. ℹ Waiting for c.my-project.catalyst-sandbox.store to be issued a certificate. This usually takes a minute or two... ✔ c.my-project.catalyst-sandbox.store is serving checkout. ``` If no certificate is issued within six minutes, the CLI removes the checkout URL again, so checkout falls back to the shared domain rather than staying broken. Run the deploy again with `--update-checkout-url` to retry. You can also set it directly. The command returns as soon as the URL is saved, so allow a minute or two for the certificate before sending shoppers to checkout: ```shell showLineNumbers={false} pnpm catalyst channels update --channel-id 123 --checkout-url https://c.my-project.catalyst-sandbox.store ``` When `channels update` points a channel at an auto-generated hostname in an interactive terminal, it offers to move checkout onto that hostname's `c.` name too. The checkout hostname belongs to the channel, not to the project. Deleting the project leaves it in place, and it's released when you [remove the channel's checkout URL](#revert-to-the-shared-checkout-domain), change the channel's site URL, or delete the channel. Until it's released, no other channel can use the name. ## Custom domains A storefront on your own domain needs a checkout subdomain on that domain, which you point at BigCommerce yourself. In addition to the [prerequisites](#prerequisites), you need: * The custom domain attached to your project and serving your storefront. See [Custom Domains](/developer/docs/storefront/catalyst/deployment/storefront-hosting/custom-domains). * Access to the DNS zone for the domain. ### Point the domain at BigCommerce Publish a `CNAME` record for the checkout subdomain pointing at the channel's **canonical** hostname — the `store--.mybigcommerce.com` value that `channels info` prints: ```text showLineNumbers={false} Type: CNAME Host: checkout Value: store--.mybigcommerce.com ``` The canonical hostname is per-channel, so use the one belonging to the channel you are configuring rather than another channel's. > **Warning** > > Do not add the checkout subdomain with [`catalyst domains > add`](/developer/docs/storefront/catalyst/reference/cli#domains-add). That > command routes a domain to your Storefront Hosting project, and your project does > not serve checkout — BigCommerce does. The checkout domain is configured on > the channel instead, with the command in the next step. ### Provision a certificate for it BigCommerce terminates TLS for checkout, so the certificate for the checkout domain is installed on the BigCommerce side, not in your Storefront Hosting project. Configure it in the store control panel's domain settings, or upload your own with the [Upsert a site's SSL/TLS certificate information](/developer/api-reference/rest/admin/management/sites/site-certificate/upsert-site-certificate) endpoint. Do this before setting the URL, so shoppers never reach a checkout domain without a valid certificate. ### Set the checkout URL ```shell showLineNumbers={false} pnpm catalyst channels update --channel-id 123 --checkout-url https://checkout.example.com ``` A bare hostname works too — `https://` is added, and any path or query is dropped, since BigCommerce expects an origin. ```shell showLineNumbers={false} pnpm catalyst channels update --channel-id 123 --checkout-url checkout.example.com ``` ### Confirm it took effect Run `channels info` again and check that the checkout URL is the one you set and that no cross-domain warning appears. ```shell showLineNumbers={false} pnpm catalyst channels info --channel-id 123 ``` ## Set it during a deploy After a successful interactive deploy, `catalyst deploy` checks the channel the storefront was built for (its `BIGCOMMERCE_CHANNEL_ID`) and offers two updates, each asked separately: 1. If the channel's site URL isn't one of the project's hostnames, it offers to point it at the deployment. 2. If the storefront is on an auto-generated hostname and checkout is on another domain, it offers to move checkout to the storefront's `c.` hostname. ```text ✔ Channel 123's site URL is https://store-abc123-123.mybigcommerce.com. Point it at this deployment? Yes ✔ Updated channel 123 site URL to https://my-project.catalyst-sandbox.store. ✔ Checkout is on https://store-abc123-1.mybigcommerce.com. Move it to https://c.my-project.catalyst-sandbox.store so shoppers stay on this domain through payment? Yes ``` Both prompts default to **No**, so pressing Enter never changes a live channel. Declining either one is saved for that channel in `.bigcommerce/project.json`, and that offer isn't made again. A channel whose checkout URL you've already customized is left alone. No prompts appear when the terminal isn't interactive or the `CI` environment variable is set, so scripted deploys are unaffected. To choose the channel and URLs yourself instead, pass the flags. They skip the offers above: ```shell showLineNumbers={false} pnpm catalyst deploy --update-site-url --update-checkout-url ``` On an auto-generated hostname, `--update-checkout-url` sets the `c.` hostname directly. On a custom domain, it prompts for the checkout URL, defaulting to the `checkout.` subdomain of the storefront's domain. Passing both flags asks which channel only once. None of this can fail the deploy: by the time it runs, your bundle is already live. ## Revert to the shared checkout domain ```shell showLineNumbers={false} pnpm catalyst channels update --channel-id 123 --remove-checkout-url ``` This removes the channel's own checkout URL, and checkout falls back to the shared domain. Traffic keeps working, so shoppers are not interrupted, but the cross-domain caveats above apply again. On an auto-generated hostname, this also releases the `c.` hostname. ## Troubleshooting | Symptom | What to try | | :------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Your checkout and storefront must be within the same main domain"** | The checkout URL does not share a main domain with the channel's storefront URL. Check the storefront URL with `channels info` and use a subdomain of it. | | **Shoppers lose their cart or session at checkout** | Run `channels info` and check whether checkout is on a different domain than the storefront. If the channel has no checkout URL of its own, it is inheriting the default channel's domain. | | **A certificate warning on the checkout domain** | On an auto-generated hostname, the certificate for the `c.` hostname is still being issued; wait a minute or two. On a custom domain, the checkout domain has no certificate on the BigCommerce side yet. Provision one in the control panel's domain settings, or with the [Site Certificate](/developer/api-reference/rest/admin/management/sites/site-certificate/upsert-site-certificate) endpoint. `catalyst domains add` does not cover this domain. | | **"wasn't issued a certificate in time, so the checkout URL was removed"** | BigCommerce didn't issue the `c.` hostname's certificate within six minutes. Checkout is back on the shared domain and keeps working. Run `catalyst deploy --update-checkout-url` to try again. | | **"Probably this domain is already in use"** when setting a `c.` hostname | Another channel still holds that name, typically one that served an earlier project with the same name. Run `catalyst channels update --channel-id --remove-checkout-url` to release it, then try again. | | **"is too long to take a checkout prefix"** | The project's auto-generated hostname is too close to the 64-character certificate limit to add `c.`, so it has no checkout hostname. Attach a [custom domain](/developer/docs/storefront/catalyst/deployment/storefront-hosting/custom-domains) to put checkout on the storefront's domain. | | **The deploy no longer offers to update a URL** | You declined that offer for the channel earlier, and the choice is saved in `.bigcommerce/project.json`. Run `catalyst channels update` to change it, or remove the channel ID from `declinedSiteUrlChannels` or `declinedCheckoutUrlChannels` to get the offer back. | | **The checkout URL is not what you set** | Confirm you targeted the right channel. Each channel has its own checkout URL, and a store can have several Catalyst channels. | | **"Re-run `catalyst auth login`"** | The access token predates the `store_channel_settings` and `store_sites` scopes the CLI now requests. Re-authenticate to mint a token that carries them. | For the full set of flags, see the [CLI Reference](/developer/docs/storefront/catalyst/reference/cli#channels-update).