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

# Build an Integration

> Build a Catalyst integration with a third-party service and contribute it to the Catalyst repository as an integration branch based on canary.

This page shows how to build a Catalyst integration for your technology and contribute it to the Catalyst repository, so store owners can add it to their composable commerce stack. For general guidelines on contributing to Catalyst, including bug fixes and features, see [CONTRIBUTING.md](https://github.com/bigcommerce/catalyst/blob/canary/CONTRIBUTING.md) in the Catalyst repository.

Catalyst integrations vary in size and complexity; some Catalyst integrations may communicate with third-party APIs and work best when paired with a related app from the [BigCommerce App Marketplace](https://www.bigcommerce.com/apps/), while others are as small as installing a package from npm.

Integrations maintained in the Catalyst upstream repository live on `integrations/*` branches, such as `integrations/makeswift` and `integrations/b2b-makeswift`. You can browse them all in the [list of integration branches](https://github.com/bigcommerce/catalyst/branches/all?query=integrations%2F) on GitHub.

The steps below cover setting up your development environment, building a minimal reference implementation of your technology into Catalyst, contributing it upstream, and keeping it up to date.

## Set up your development environment

The default branch of the Catalyst repository is `canary`, where active development happens. Since you'll ultimately be contributing code back up to the Catalyst upstream GitHub repository, create a new branch off of `upstream/canary` in your local Catalyst fork:

```shell showLineNumbers={false}
git fetch upstream canary
git checkout -b integrations/<INTEGRATION_NAME> upstream/canary
```

Then write the code your integration needs.

## Build your integration

Follow these practices, which come from the Catalyst team's experience building integrations:

1. Keep your integration code as maintainable as possible. Keep the integration-specific changes small and contained, outside of files that change often in `canary` where you can. The fewer files your integration touches, the fewer merge conflicts you'll need to resolve each time you pull in the latest changes from `upstream/canary`.
2. Explicitly call out when your integration makes use of newly introduced environment variables. For example, the [`integrations/makeswift` branch](https://github.com/bigcommerce/catalyst/compare/canary...integrations/makeswift) adds a new environment variable called `MAKESWIFT_SITE_API_KEY`; by explicitly listing newly introduced environment variables in a version-controlled file like `.env.example`, it makes it obvious to the consumers of your integration when they need to add new environment variables to make your integration work.

## Open a PR to add your integration upstream

When your branch is ready for public use, open a new issue in the Catalyst upstream GitHub repository. In your issue, request the creation of an `integrations/<INTEGRATION_NAME>` branch. Once the branch is created, you can target it with your pull request to contribute your integration code back upstream.

## Keep your integration up to date

An integration branch should mirror `canary` apart from its own integration code, so keep it in sync by merging the latest `canary` into it rather than rebasing. Create a sync branch from your integration branch, merge `upstream/canary`, and resolve any conflicts:

```shell showLineNumbers={false}
git fetch upstream
git checkout -B sync-integrations-<INTEGRATION_NAME> upstream/integrations/<INTEGRATION_NAME>
git merge upstream/canary
git push origin sync-integrations-<INTEGRATION_NAME>
```

Then open a PR from your fork's `sync-integrations-<INTEGRATION_NAME>` branch into the upstream `integrations/<INTEGRATION_NAME>` branch. Don't squash or rebase-and-merge this PR: it must land as a true merge commit, so that it establishes a new merge base between `canary` and your integration branch and you don't resolve the same conflicts again next time.

For the full procedure the Catalyst team follows to keep `integrations/makeswift` in sync with `canary`, see [Keeping `integrations/makeswift` in sync with `canary`](https://github.com/bigcommerce/catalyst/blob/canary/CONTRIBUTING.md#keeping-integrationsmakeswift-in-sync-with-canary) in `CONTRIBUTING.md`.

## Next steps

* Read [CONTRIBUTING.md](https://github.com/bigcommerce/catalyst/blob/canary/CONTRIBUTING.md) for the review process and general contribution guidelines.
* Browse the existing [integration branches](https://github.com/bigcommerce/catalyst/branches/all?query=integrations%2F) for examples of how other integrations are structured.