# Connect API overview

Overview of the concepts related to the Connect API.

The Connect API lets you manage [Connectors](/connect/connect-api-overview.md#connectors-and-connectorstaged) and [Deployments](/connect/connect-api-overview.md#deployments) programmatically. Use it to publish integrations built with Connect applications and deploy them to your Project.

The Connect API is a separate API from the Composable Commerce HTTP API. It has its own [hosts and authorization scopes](/connect/hosts-and-authorization.md).

## Resources

### Connectors and ConnectorStaged

[Connectors](/connect/connectors.md) and [ConnectorStaged](/connect/connectors-staged.md) represent the packaged integration that Connect hosts and deploys.

A [ConnectorStaged](/connect/connectors-staged.md#connectorstaged) is the working version of a Connector. It references the GitHub repository containing the source code of the [Connect applications](/connect/overview.md#connect-applications). A ConnectorStaged is used to manage the Connector lifecycle before it is ready for production.

When a ConnectorStaged is published for the first time, a read-only [Connector](/connect/connectors.md#connector) is created. Subsequent republishing of this ConnectorStaged updates this Connector. Clients can deploy Connectors to their Projects using [Deployments](/connect/connect-api-overview.md#deployments).

The following table summarizes the key differences between ConnectorStaged and Connector:

|  | ConnectorStaged | Connector |
| --- | --- | --- |
| Purpose | Used during development, testing, and publishing phases. | A production-ready Connector that is available for deployment. |
| Mutability | Can be updated using update actions. | Read-only. Update the ConnectorStaged and publish a new version to make changes. |
| Preview | Supports preview Deployments via the `isPreviewable` flag. | Not applicable. |
| Status | Tracks status via the `status` field (for example, `Draft`, `Published`). | Always represents a published Connector. |

### Deployments

A [Deployment](/connect/deployments.md#deployment) represents a published [Connector](/connect/connect-api-overview.md#connectors-and-connectorstaged) that has been deployed to a Project. When you create a Deployment, Connect builds and hosts the underlying Connect applications and connects them to your Project.

Deployments can be one of three types:

- `preview`: a test Deployment based on a ConnectorStaged. Use this to verify the behavior of your Connect applications before publishing.
- `sandbox`: a non-production Deployment based on a published Connector. Use this for integration testing in a non-production environment.
- `production`: a production Deployment based on a published Connector. Can only be deployed to non-trial Projects.

### Deployment Logs

[Deployment Logs](/connect/deployment-logs.md) capture the output from Connect applications running inside a Deployment. Use them to debug issues with your Connect applications during and after deployment.

### Common Types

The Connect API uses shared data types across its resources. These include types for Regions, Deployment status, Connector status, and environment variable configurations. For a full reference, see [Common Types](/connect/common-types.md).

### Errors

The Connect API returns structured error responses when a request fails. For a full list of error codes and their descriptions, see [Errors](/connect/errors.md).

## Connector lifecycle

Using the Connect API, the standard lifecycle of a Connector from development to production deployment is as follows:

1. Create a [ConnectorStaged](/connect/connectors-staged.md#connectorstaged) that references the GitHub repository containing your Connect applications.
2. Request a preview build using the [Preview Connector](/connect/connectors-staged.md#preview-connector) update action to verify the ConnectorStaged is deployable.
3. If `isPreviewable` is `true`, create a preview [Deployment](/connect/deployments.md#deployment) to test the ConnectorStaged in your Project.
4. Publish the ConnectorStaged using the [Publish](/connect/connectors-staged.md#publish) update action. This creates a [Connector](/connect/connectors.md#connector).
5. Create a production [Deployment](/connect/deployments.md#deployment) referencing the published Connector.

For a visual summary of the lifecycle across the CLI, API, and Merchant Center, see [Connect workflow](/connect/connect-workflow.md).

If you only need to deploy the Connector within your own organization, set `certification` to `false` when publishing the ConnectorStaged. This publishes a private Connector without going through the [certification process](/connect/certification.md).

### Update a Connector

A published [Connector](/connect/connectors.md#connector) is read-only. To update it, make changes to the corresponding [ConnectorStaged](/connect/connectors-staged.md#connectorstaged). For example, by using the [Set Repository](/connect/connectors-staged.md#set-repository) update action to point to a new Git tag, and then republish using the [Publish](/connect/connectors-staged.md#publish) update action. This updates the Connector with the latest changes from the ConnectorStaged.

### Delete a Connector

To delete a Connector, delete its [ConnectorStaged](/connect/connectors-staged.md#delete-connectorstaged) using the [Delete ConnectorStaged](/connect/connectors-staged.md#delete-connectorstaged) endpoint. Deleting a ConnectorStaged also deletes the associated published Connector.

A ConnectorStaged can only be deleted if neither it nor its published Connector has any active Deployments.

## Alternatives to the Connect API

You can also manage Connectors and Deployments using the [Merchant Center](/merchant-center/connect.md) or the [Connect CLI](/connect/cli.md), without writing API requests directly.

In the Merchant Center, Connectors are referred to as **Organization Connectors** when they belong to your Organization, and Deployments are referred to as **installations**.

The Connect CLI provides commands that map directly to Connect API operations, such as creating ConnectorStaged, publishing, and managing Deployments. For more information, see [Connect CLI](/connect/cli.md).

## Related pages

- [Area overview page with navigation](/connect.md)
- [Next page: Hosts and authorization](/connect/hosts-and-authorization.md)
- [Search documentation and API specs](/search.md)