DocsStorefrontCatalystGuides

Manually Create a Catalyst Channel

This guide shows you how to create a Catalyst channel, its site, checkout URL, and routes from scratch with the REST Management API, and how to optionally create and attach a Makeswift site.

Prerequisites

You need the same prerequisites as the other Catalyst setup paths, including the control panel permissions to create channels and store-level API accounts. You also need an available storefront seat.

Create an API token

You also need an API token to authenticate requests to the REST Management API. The token must have the following OAuth scopes:

  • Channel Settings (modify) — store_channel_settings
  • Sites & Routes (modify) — store_sites

In the control panel, go to Settings → Store-level API accounts and click Create API Account. Add the scopes above when creating the account, then click Save and copy the Access token to use in the next steps.

Create a Catalyst channel

Using the token from Create an API token and your store hash, send a POST request to the Create a channel endpoint. Use type: "storefront" and platform: "catalyst" for a Catalyst channel.

curl -X POST https://api.bigcommerce.com/stores/{store_hash}/v3/channels \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {access_token}" \
  -d '{
    "name": "My Catalyst Storefront",
    "type": "storefront",
    "platform": "catalyst",
    "status": "prelaunch"
  }'

The response includes the new channel’s id; use it when creating the site and checkout URL in the next steps.

Add the headless site URL

You need a primary domain for your storefront (and a separate domain for checkout, which you set in the next section). Subdomains are permitted. Ensure each domain is not already in use by another channel or the default storefront; the API does not verify domain ownership. Use the Create a site endpoint with your channel ID and primary storefront domain so BigCommerce knows where your Catalyst storefront is (or will be) hosted.

curl -X POST https://api.bigcommerce.com/stores/{store_hash}/v3/sites \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {access_token}" \
  -d '{
    "url": "https://mystore.com/",
    "channel_id": {channel_id}
  }'

Use the same {store_hash} and {access_token} from when you created the channel. Replace {channel_id} with the channel id from the create-channel response. Use your actual primary storefront URL for url (for example, https://www.mystore.com/ or your production domain).

Add a checkout URL

Catalyst uses Redirected Checkout: shoppers are sent to BigCommerce hosted checkout. Set the checkout domain with the Upsert a site’s checkout URL endpoint. The checkout URL must be a subdomain of your primary storefront URL (same main domain). You can configure www_redirect via the Settings API if needed.

curl -X PUT https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/site/checkout-url \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {access_token}" \
  -d '{
    "url": "https://checkout.mystore.com"
  }'

Use the same {store_hash} and {access_token} as before. Replace {channel_id} with your channel id. Set url to your checkout domain (for example, https://checkout.mystore.com if your primary site is https://mystore.com/). Keep in mind that your checkout domain must be a subdomain of your primary storefront URL.

Add a third-party SSL certificate to the checkout domain (optional)

To use your own third-party (3P) SSL certificate for the checkout domain, upload it with the Upsert a site’s SSL/TLS certificate information endpoint.

To set the checkout domain itself with the Catalyst CLI, and for the requirement that it share a main domain with the storefront, see Checkout Domains.

Add channel menus

Channels created with the API don’t get control panel navigation by default. Use the Create channel menus endpoint to define the Channel Manager sidebar for your Catalyst channel. The request creates or replaces the list of menu sections.

Each entry in bigcommerce_protected_app_sections enables a BigCommerce-provided, channel-specific settings page (protected sections override storewide defaults for that channel). See Building Storefront Channels — Protected UI sections for context.

curl -X POST "https://api.bigcommerce.com/stores/{store_hash}/v3/channels/{channel_id}/channel-menus" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {access_token}" \
  -d '{
    "bigcommerce_protected_app_sections": [
      "storefront_settings",
      "currencies",
      "domains",
      "notifications",
      "social",
      "localization",
      "pages",
      "checkout",
      "payments",
      "data_solutions",
      "script_manager"
    ]
  }'

Replace {channel_id} with your channel id. Adjust the array to match the sections you need; valid values are listed in the endpoint reference (for example overview, carousel, and the sections shown above). You can also supply custom_app_sections with title and query_path for app-specific menu items.

Set up routes for the channel

A channel has a site. Routes tell BigCommerce how URLs map to pages on your headless storefront (home, cart, product, login, and so on). Catalyst’s withRoutes proxy and the GraphQL Storefront API route() node depend on these routes.

Get your site ID

Send a request to list sites for your store and identify the site for your Catalyst channel:

curl -X GET "https://api.bigcommerce.com/stores/{store_hash}/v3/sites" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: {access_token}"

Use the id of the site that corresponds to your Catalyst channel as site_id in the next step. You can find your store hash in the control panel or in your app’s credentials.

Configure routes

Send a PUT request to update the site’s routes. The body replaces the full set of routes for the site. Include at least the following route types so the storefront and checkout session syncing work correctly:

curl -X PUT "https://api.bigcommerce.com/stores/{store_hash}/v3/sites/{site_id}/routes" \
  -H "Content-Type: application/json" \
  -H "X-Auth-Token: {access_token}" \
  -d '[
  {"type": "home", "matching": "*", "route": "/"},
  {"type": "cart", "matching": "*", "route": "/cart/"},
  {"type": "login", "matching": "*", "route": "/login/"},
  {"type": "logout", "matching": "*", "route": "/logout/"},
  {"type": "search", "matching": "*", "route": "/search/"},
  {"type": "account", "matching": "*", "route": "/account/"}
]'

Replace {site_id} with the site id from the list-sites response. Use the same {store_hash} and token as before.

Connect your Catalyst project to the channel

If you don’t already have a local Catalyst project, follow CLI Installation to scaffold one. From your project directory, link it to the channel you created:

pnpm catalyst channels link --channel-id {channel_id}

See API Accounts for background on store-level vs. app-level accounts and their scopes, and the channels link reference for all available flags (including --access-token and --store-hash, for a fully non-interactive run). The command generates an .env.local file with the environment variables needed to run Catalyst, including the GraphQL Storefront API token and channel ID. If you’re setting tokens manually instead, see Environment variables.

Create a Makeswift site and connect it to the Catalyst channel

Start by creating a site in Makeswift for your Catalyst storefront.

This requires a Makeswift-connected Catalyst project. The CLI scaffolds @bigcommerce/catalyst-core, which has no Makeswift integration, unless you pass --gh-ref @bigcommerce/catalyst-makeswift@latest. See Makeswift.

Get the site API key

In the Makeswift dashboard, go to Settings → Host and copy the site API key. You use this as the value for MAKESWIFT_SITE_API_KEY in your Catalyst app.

Set the environment variable in Catalyst

Set MAKESWIFT_SITE_API_KEY in your Catalyst’s .env.local file for local development. This determines which Makeswift site the storefront uses. For details, see Environment variables.

Set the Host URL in Makeswift

In Makeswift, set the Host URL to your storefront URL so Makeswift can serve content to the correct host:

  • For local development, Catalyst uses http://localhost:3000 by default.
  • For production, set the Host URL to your deployed storefront URL. On Native Hosting, channels update sets this for you, but you still set the production site’s API key yourself; see Makeswift on Native Hosting. On Vercel, see Deploying to Vercel.

Next steps