Checkout Domains

Beta

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.

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.

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. 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.

Check the current configuration

Run channels info to see where a channel’s storefront and checkout currently point:

pnpm catalyst channels info --channel-id 123

✔ 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:

ℹ 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. It starts with its preview URL as the storefront and its own checkout URL on the same preview domain:

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, 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:

⚠ 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 <your-project>.catalyst-sandbox.store. Its checkout hostname is the same hostname with a c. prefix:

Storefront  https://<your-project>.catalyst-sandbox.store
Checkout    https://c.<your-project>.catalyst-sandbox.store

There is nothing to set up beforehand. Setting c.<your-project>.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). The CLI sets the checkout URL, waits for the certificate, and confirms when checkout is being served:

✔ 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:

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, 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, you need:

The custom domain attached to your project and serving your storefront. See 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-<hash>-<channel-id>.mybigcommerce.com value that channels info prints:

Type:   CNAME
Host:   checkout
Value:  store-<your-store-hash>-<your-channel-id>.mybigcommerce.com

The canonical hostname is per-channel, so use the one belonging to the channel you are configuring rather than another channel’s.

Do not add the checkout subdomain with catalyst 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 endpoint.

Do this before setting the URL, so shoppers never reach a checkout domain without a valid certificate.

Set the checkout URL

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.

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.

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:

If the channel’s site URL isn’t one of the project’s hostnames, it offers to point it at the deployment.
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.

✔ 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:

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

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 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 <that-channel> --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 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.