Connectors

Connect Add-On

A Connector is a production-ready integration for commercetools Projects.

After a ConnectorStaged is published, 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.

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:
id
​
String
​
id of the Connector
region
​
String
​
Region in which the Project is hosted.
Response:
200

Connector

as
application/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",
  "integrationTypes": ["other"],
  "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",
          "required": true,
          "default": null
        }
      ],
      "securedConfiguration": [
        {
          "key": "CONFIG_SECRET_KEY",
          "description": "config secret description",
          "required": true
        }
      ]
    }
  ],
  "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:
key
​
String
​
key of the Connector
region
​
String
​
Region in which the Project is hosted.
Response:
200

Connector

as
application/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",
  "integrationTypes": ["other"],
  "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",
          "required": true,
          "default": null
        }
      ],
      "securedConfiguration": [
        {
          "key": "CONFIG_SECRET_KEY",
          "description": "config secret description",
          "required": true
        }
      ]
    }
  ],
  "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 are based on matches found in the name and description fields of a Connector.
limit
​
Int64
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int64
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
sort
​
String
​
The parameter can be passed multiple times.
private
​
Boolean
​
Whether only Connectors assigned to your Project are retrieved. If false, 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.
integrationTypes
​
IntegrationType
​
Only search for Connectors with a specified integrationType.
The parameter can be passed multiple times.
Response:
200

ConnectorSearchPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://connect.{region}.commercetools.com/connectors/search -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ConnectorSearchPagedQueryResponsejson
{
  "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",
      "integrationTypes": ["other"],
      "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",
              "required": true,
              "default": null
            }
          ],
          "securedConfiguration": [
            {
              "key": "CONFIG_SECRET_KEY",
              "description": "config secret description",
              "required": true
            }
          ]
        }
      ],
      "private": false,
      "supportedRegions": ["us-central1.gcp", "europe-west1.gcp"],
      "certified": true
    }
  ]
}

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: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​

Name of the Connector.

description​
String​

Description of the Connector.

integrationTypes​
Array of IntegrationType​

Integration types of the Connector. Can be used to filter search and query results.

creator​
Creator​

Owner of the Connector.

repository​
Repository​

GitHub repository details of the Connector.

configurations​
Array of ConnectorConfigurationApplication​

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

apiClient​
ConnectorApiClient​

Configuration for the API Client used for automatically generating API Client credentials.

private​
Boolean​
Whether only commercetools Projects specified in privateProjects can access the Connector.
globalConfiguration​
ConnectorGlobalConfiguration​

Global configuration applied to all applications in the Deployment.

supportedRegions​
Array of Region​
If provided, Connectors can only be deployed in these Regions. If not provided, Connectors can be deployed in any supported Region. For faster request processing, we recommend adding only the required Region.
certified​
Boolean​

Whether the Connector is certified.

documentationUrl​
String​

URL to the documentation of the Connector.

ConnectorReference

Reference to a Connector or ConnectorStaged. Either id or key is required.
id​
String​

Unique identifier of the referenced Connector.

version​
Int64​

Version of the referenced Connector.

key​
String​

User-defined unique identifier of the referenced Connector.

staged​
Boolean​
Whether a previewable ConnectorStaged must be referenced in id or key instead of the published Connector. The isPreviewable field of the ConnectorStaged must be true to reference a previewable ConnectorStaged.
Default: false​
Example: json
{
  "key": "connector-key",
  "version": 1
}

ConnectorSearchPagedQueryResponse

PagedQueryResult with results containing an array of Connector.
limit​
Int64​

The maximum number of Connectors returned.

offset​
Int64​

The offset of the Connectors returned.

count​
Int64​

The number of Connectors returned.

total​
Int64​

The total number of Connectors matching the query.

results​
Array of Connector​

Connectors matching the query.