Connectors

Connectors represent a certified and listed integration that can be deployed by clients.

After a ConnectorStaged is certified, a Connector is created containing all the information from the ConnectorStaged. These are production versions of your Connector that are available for clients to deploy.

Connectors are read-only. If you are a creator and want to make changes to your Connector, you should make the changes to the ConnectorStaged and then use the Publish update action.

Representations

Connector

id
String

Unique identifier of the Connector.

version
Int

Current version of the Connector.

key
String

User-defined unique identifier of the Connector.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name
String

Name of the Connector.

description
String

Description of the Connector.

creator

Owner of the Connector.

repository

GitHub repository details of the Connector.

configurations

Configurations needed by Connectors for hosting. Loaded as environment variables in the workload.

private
Boolean

If true, only Composable Commerce Projects specified in privateProjects can access the Connector.

supportedRegions
Array of Region

If not empty, Connectors can only be deployed in these Regions. If empty, Connectors can be deployed in any supported Region.

certified
Boolean

If true, the Connector is certified.

documentationUrl
String

URL to the documentation of the Connector.

ConnectorReference

Reference to a Connector. Either id or key is required.

id
String

Unique identifier of the referenced Connector.

version
Int

Version of the referenced Connector.

key
String

User-defined unique identifier of the referenced Connector.

staged
Boolean

If true, the previewable ConnectorStaged will be referenced instead of the certified Connector. The isPreviewable field of the ConnectorStaged must be true to reference a previewable ConnectorStaged.

Default: false
Example: json
{
"key": "connector-key",
"version": 1
}

Get Connector

Get Connector by ID

GET
https://connect.{region}.commercetools.com/connectors/{id}
OAuth 2.0 Scopes:
manage_project:{projectKey} , manage_connectors:{projectKey} , view_connectors:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

id
String

id of the Connector

Response:
200Connectorasapplication/json
Request Example:cURL
curl --get https://connect.{region}.commercetools.com/connectors/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Connectorjson
{
"id": "5ab3edcd-9d23-4934-8f48-256805253119",
"key": "connector-key",
"version": 1,
"name": "Connector's name",
"description": "Connector's description",
"creator": {
"title": "Mr",
"name": "John Doe",
"email": "john.doe@example.com",
"company": "commercetools",
"noOfContributors": 200
},
"repository": {
"url": "git@github.com:commercetools/connect-application-kit.git",
"tag": "0.0.0"
},
"configurations": [
{
"applicationName": "app-1",
"applicationType": "service",
"standardConfiguration": [
{
"key": "CONFIG_KEY",
"description": "config key description"
}
],
"securedConfiguration": [
{
"key": "CONFIG_SECRET_KEY",
"description": "config secret description"
}
]
}
],
"private": false,
"supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
"certified": true
}

Get Connector by Key

GET
https://connect.{region}.commercetools.com/connectors/key={key}
OAuth 2.0 Scopes:
manage_project:{projectKey} , manage_connectors:{projectKey} , view_connectors:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

key
String

key of the Connector

Response:
200Connectorasapplication/json
Request Example:cURL
curl --get https://connect.{region}.commercetools.com/connectors/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Connectorjson
{
"id": "5ab3edcd-9d23-4934-8f48-256805253119",
"key": "connector-key",
"version": 1,
"name": "Connector's name",
"description": "Connector's description",
"creator": {
"title": "Mr",
"name": "John Doe",
"email": "john.doe@example.com",
"company": "commercetools",
"noOfContributors": 200
},
"repository": {
"url": "git@github.com:commercetools/connect-application-kit.git",
"tag": "0.0.0"
},
"configurations": [
{
"applicationName": "app-1",
"applicationType": "service",
"standardConfiguration": [
{
"key": "CONFIG_KEY",
"description": "config key description"
}
],
"securedConfiguration": [
{
"key": "CONFIG_SECRET_KEY",
"description": "config secret description"
}
]
}
],
"private": false,
"supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
"certified": true
}

Search Connectors

GET
https://connect.{region}.commercetools.com/connectors/search

Retrieves all available Connectors.

OAuth 2.0 Scopes:
manage_project:{projectKey} , manage_connectors:{projectKey} , view_connectors:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

Query parameters:
text
String

The text to search for. For example, as supplied by a user through a search input field. Search results will be based on if the name and description fields of a Connector contain this text.

limit
Int
offset
Int

Number of elements skipped.

sort
String
The parameter can be passed multiple times.
private
Boolean

If true then only Connectors assigned to your Project are retrieved. If false then all available Connectors are retrieved.

creator.company
String

Company name of a creator to search for.

id
String

id of a Connector to search for.

The parameter can be passed multiple times.
key
String

key of a Connector to search for.

The parameter can be passed multiple times.
Response:
200

Paged

asapplication/json
Request Example:cURL
curl --get https://connect.{region}.commercetools.com/connectors/search -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Pagedjson
{
"offset": 0,
"limit": 20,
"total": 1,
"count": 1,
"results": [
{
"id": "5ab3edcd-9d23-4934-8f48-256805253119",
"key": "connector-key",
"version": 1,
"name": "Connector's name",
"description": "Connector's description",
"creator": {
"title": "Mr",
"name": "John Doe",
"email": "john.doe@example.com",
"company": "commercetools",
"noOfContributors": 200
},
"repository": {
"url": "git@github.com:commercetools/connect-application-kit.git",
"tag": "0.0.0"
},
"configurations": [
{
"applicationName": "app-1",
"applicationType": "service",
"standardConfiguration": [
{
"key": "CONFIG_KEY",
"description": "config key description"
}
],
"securedConfiguration": [
{
"key": "CONFIG_SECRET_KEY",
"description": "config secret description"
}
]
}
],
"private": false,
"supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
"certified": true
}
]
}