BigCommerce Docs

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 pointing that domain at a subdomain of your own storefront domain with the Catalyst CLI.

The Catalyst CLI is generally available, but Native Hosting is currently in closed beta. There may be breaking changes to the Native Hosting APIs as we finalize them. To express interest in gaining access, fill out the Native 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: pointing a channel’s site URL at a new domain does not move its checkout URL with it.

Prerequisites

A custom domain attached to your project and serving your storefront. See Custom Domains.
The channel’s site URL already pointing at that domain. See channels update.
Store credentials available to the CLI, either from pnpm catalyst auth login or through --store-hash and --access-token. See Authentication.
Access to the DNS zone for the domain.

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

When 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. Every
  channel starts this way, so nothing here is misconfigured — but it still needs
  a checkout URL of its own 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 has its own checkout URL (checkout.old-domain.com), but it doesn't
  look like it shares a main domain with the 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.

Set a checkout 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 Native 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 Native 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

catalyst deploy can prompt for both channel URLs after a successful deploy, which is convenient when you are bringing a custom domain up for the first time:

pnpm catalyst deploy --update-site-url --update-checkout-url

The checkout prompt defaults to the checkout. subdomain of the channel’s storefront domain. Passing both flags asks which channel only once. Neither flag can fail the deploy — by the time they run, your bundle is already live.

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. Channels on an auto-generated hostname cannot use a custom checkout domain. The same-domain rule would require checkout.<your-project>.catalyst-sandbox.store, and a certificate cannot be issued for a subdomain at that depth on a BigCommerce-managed zone.

Those channels use the shared checkout domain instead. Checkout works, but it is cross-domain from the storefront, so treat the setup as suitable for development and preview rather than for production traffic. Attaching a custom domain is the prerequisite for putting checkout on your own domain.

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.

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