Choose a connection point

Two questions narrow every integration requirement to one or two connection points: which way does the data move, and what starts the exchange? Volume and consistency then decide between the remaining options.

Zen Electron has five integration requirements on one whiteboard. This page sorts them before anyone chooses a technology.

Connection points at a glance

Each summary below describes how a connection point behaves and links to its reference. Use the reference for field lists and exact limits.

Direct API

Import API

• Monitor ImportOperations until they reach a final state. Missing references must resolve within the operation lifetime; see ImportOperations and reference resolution for the current lifecycle and retry behavior.
• Changes are not visible immediately, so the Import API doesn't suit flows that need the result in the same request.

Subscriptions

• Choose the notification payload and queue from the supported Subscription representations.
• Plan fan-out in the queue service instead of creating one Subscription per consumer. This reduces pressure on the current Subscription limit.

API Extensions

• An API Extension applies to requests from every API client, including the Merchant Center.
• Each Extension supports a defined set of resources. Before selecting an Extension for a resource, check the supported resources, conditional triggers, Extension chaining, and the Extension input.

Merchant Center customizations

Choose by direction and trigger

Start with two questions: which way does the data move, and what starts the exchange? The following decision tree maps the answers to a connection point:

The tree has two refinements:

• Inbound flows can use either the Direct API or the Import API. Whether a source pushes changes, a schedule starts a job, or you load data in bulk, volume and consistency decide. Choose the Direct API when volumes are low or the caller needs the result immediately. Choose the Import API for large volumes when a short delay is acceptable.
• Scheduled flows are not a separate connection point. A job runs on a schedule and then calls the Direct API or the Import API.

The task view

Teams often describe integrations as tasks. The following table maps each task to the direction and trigger, and then to the usual connection point:

Application-side logic or an API Extension

For in-request rules, you have two options:

• Application-side logic: your storefront or backend-for-frontend (BFF) runs the rule before it calls commercetools.
• API Extension: commercetools calls your service during the write.

The deciding question is which clients the rule must cover. Application-side logic only covers requests that pass through your application. An API Extension covers every API client, including the Merchant Center, a PIM writing Products, and other integrations.

Don't use an API Extension for side effects, such as sending an email or pushing an Order to an ERP. Side effects belong in a Subscription consumer, so they don't slow down or fail the original request.

Worked example: classify Zen Electron's requirements

Zen Electron's team classifies each requirement by direction and trigger before choosing a connection point. The team labels the five integrations A to E, and the rest of this module uses the same labels:

Same-day metro delivery eligibility: application-side logic or an API Extension

• Application-side logic: the Electronics High Tech storefront calls the eligibility service and sets the Custom Field before it updates the Cart. Carts created from the Merchant Center or by other clients don't get the value.
• API Extension: commercetools calls the eligibility service whenever a matching Cart changes, regardless of the client. Customer service agents creating Carts in the Merchant Center also get correct eligibility.

If Electronics High Tech only takes same-day orders through its storefront, application-side logic is enough. If agents also create Carts for customers, choose the Extension.

POST https://api.australia-southeast1.gcp.commercetools.com/zen-electron/extensions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "key": "metro-delivery-eligibility",
  "destination": {
    "type": "HTTP",
    "url": "https://eligibility.example.com/cart-extension",
    "authentication": {
      "type": "AuthorizationHeader",
      "headerValue": "Bearer {extension_secret}"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"],
      "condition": "shippingAddress has changed"
    }
  ],
  "timeoutInMs": 1000
}

• condition uses Query Predicate syntax. The has changed operator evaluates to true for every create, so the Extension is called for every new Cart, with or without a shipping address. On updates, it's called only when the address changes, including when it's removed. The handler decides eligibility from the country, and treats a Cart with no address as not eligible. Conditional triggers lists the evaluation outcomes.
• timeoutInMs is optional. Price the contract explains how to choose a value.
• Authentication values, such as headerValue, are partially hidden when you retrieve the Extension. See AuthorizationHeaderAuthentication.

The order confirmation Subscription

POST https://api.australia-southeast1.gcp.commercetools.com/zen-electron/subscriptions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "key": "order-created-to-sqs",
  "destination": {
    "type": "SQS",
    "queueUrl": "https://sqs.ap-southeast-2.amazonaws.com/123456789012/zen-order-events",
    "region": "ap-southeast-2",
    "authenticationMode": "IAM"
  },
  "messages": [
    { "resourceTypeId": "order", "types": ["OrderCreated"] }
  ]
}

• Prefer IAM for authenticationMode. SQSDestination defines the queue type, the permissions to grant before you create the Subscription, and the default authentication mode.
• SubscriptionDraft defines which of messages, changes, and events the request must set.
• This request suits a consumer on your own infrastructure. If the consumer runs as a Connect event application instead, as in Deploy and build Connectors, its postDeploy script creates the Subscription with the destination that Connect provides, so you don't create it yourself.

Key takeaways

• Direction and trigger narrow the choice of connection point. Volume and consistency decide between the Direct API and the Import API for inbound flows.
• Inbound pushes arrive at your endpoint, which then calls the Direct API or the Import API.
• Scheduled flows are a job calling the Direct API or the Import API, not a separate connection point.
• Choose an API Extension over application-side logic when a rule must hold for every API client.
• Use Subscriptions, not Extensions, for side effects.
• Fan notifications out in the queue service instead of creating one Subscription per consumer. Set timeoutInMs on each Extension for the work it does.

Test your knowledge