Overview of the concepts related to the Connect API.
The Connect API lets you manage Connectors and 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.
Resources
Connectors and ConnectorStaged
Connectors and ConnectorStaged represent the packaged integration that Connect hosts and deploys.
A ConnectorStaged is the working version of a Connector. It references the GitHub repository containing the source code of the 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 is created. Subsequent republishing of this ConnectorStaged updates this Connector. Clients can deploy Connectors to their Composable Commerce Projects using 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 represents a published Connector that has been deployed to a Composable Commerce 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 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.
Errors
The Connect API returns structured error responses when a request fails. For a full list of error codes and their descriptions, see Errors.
Connector lifecycle
Using the Connect API, the standard lifecycle of a Connector from development to production deployment is as follows:
- Create a ConnectorStaged that references the GitHub repository containing your Connect applications.
- Request a preview build using the Preview Connector update action to verify the ConnectorStaged is deployable.
- If
isPreviewableistrue, create a preview Deployment to test the ConnectorStaged in your Project. - Publish the ConnectorStaged using the Publish update action. This creates a Connector.
- Create a production Deployment referencing the published Connector.
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.Update a Connector
A published Connector is read-only. To update it, make changes to the corresponding ConnectorStaged. For example, by using the Set Repository update action to point to a new Git tag, and then republish using the Publish update action. This updates the Connector with the latest changes from the ConnectorStaged.
Delete a Connector
To delete a Connector, delete its ConnectorStaged using the 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 or the Connect CLI, 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.