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

# Manually Create a Catalyst Channel

> Create a Catalyst channel, site, checkout URL, and routes with the REST Management API instead of the control panel, and optionally attach a Makeswift site.

This guide shows you how to create a Catalyst channel, its site, checkout URL, and routes from scratch with the [REST Management API](/developer/api-reference/about-our-apis#rest-store-management-apis), and how to optionally create and attach a Makeswift site.

## Prerequisites

You need the same [prerequisites](/developer/docs/storefront/catalyst/getting-started/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](/developer/api-reference/rest/admin/management/channels/create-channel) endpoint. Use `type: "storefront"` and `platform: "catalyst"` for a Catalyst channel.

```bash
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](/developer/api-reference/rest/admin/management/sites/create-site) endpoint with your channel ID and primary storefront domain so BigCommerce knows where your Catalyst storefront is (or will be) hosted.

```bash
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](/developer/docs/storefront/catalyst/deployment/overview#redirected-checkout): shoppers are sent to BigCommerce hosted checkout. Set the checkout domain with the [Upsert a site's checkout URL](/developer/api-reference/rest/admin/management/channels/site-checkout-url/update-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](/developer/api-reference/rest/admin/management/settings) API if needed.

```bash
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](/developer/api-reference/rest/admin/management/sites/site-certificate/upsert-site-certificate) 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](/developer/docs/storefront/catalyst/deployment/storefront-hosting/checkout-domains).

## Add channel menus

Channels created with the API don't get control panel navigation by default. Use the [Create channel menus](/developer/api-reference/rest/admin/management/channels/menus/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](/developer/docs/integrations/channels/guide/building-storefront-channels#protected-ui-sections) for context.

```bash
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](/developer/docs/storefront/catalyst/development/middleware#with-routes) and the GraphQL Storefront API [route()](/developer/api-reference/graphql/storefront#definition-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:

```bash
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:

```bash
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](/developer/docs/storefront/catalyst/getting-started/cli-installation) to scaffold one. From your project directory, link it to the channel you created:

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

See [API Accounts](/developer/docs/overview/api-fundamentals/api-accounts) for background on store-level vs. app-level accounts and their scopes, and the [`channels link`](/developer/docs/storefront/catalyst/reference/cli#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](/developer/docs/storefront/catalyst/reference/environment-variables#bigcommerce_storefront_token).

## Create a Makeswift site and connect it to the Catalyst channel

Start by creating a site in [Makeswift](https://www.makeswift.com/) 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](/developer/docs/storefront/catalyst/makeswift/overview).

### 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](/developer/docs/storefront/catalyst/reference/environment-variables#makeswift_site_api_key).

### 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 Storefront Hosting, `channels update` sets this for you, but you still set the production site's API key yourself; see [Makeswift on Storefront Hosting](/developer/docs/storefront/catalyst/deployment/storefront-hosting/makeswift). On Vercel, see [Deploying to Vercel](/developer/docs/storefront/catalyst/deployment/vercel#update-the-makeswift-host-url).

## Next steps

* Start your project locally with `pnpm run dev`, as described in [CLI Installation](/developer/docs/storefront/catalyst/getting-started/cli-installation).
* [Deploy your storefront](/developer/docs/storefront/catalyst/deployment/overview) to Storefront Hosting or another hosting provider.
* [Create custom components](/developer/docs/storefront/catalyst/makeswift/custom-components) that are editable in Makeswift.