API Extensions

An API Extension is applied to API calls from all clients, including those provided by commercetools, like the Merchant Center.

API Extensions are available for the following resources:

• Carts
• Orders
• Payments
• Customers
• Customer Groups
• Quote Requests
• Staged Quotes
• Quotes
• Business Units B2B
• Shopping Lists

Representations

Get Extension

Get Extension by ID

curl --get https://api.{region}.commercetools.com/{projectKey}/extensions/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 1,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2017-01-25T14:14:22.417Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-extension"
}

Get Extension by Key

curl --get https://api.{region}.commercetools.com/{projectKey}/extensions/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 1,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2017-01-25T14:14:22.417Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-extension"
}

Query Extensions

curl --get https://api.{region}.commercetools.com/{projectKey}/extensions -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
      "version": 1,
      "createdAt": "2017-01-25T14:14:22.417Z",
      "lastModifiedAt": "2017-01-25T14:14:22.417Z",
      "destination": {
        "type": "HTTP",
        "url": "https://example.org/extension"
      },
      "triggers": [
        {
          "resourceTypeId": "cart",
          "actions": ["Create"]
        }
      ]
    }
  ]
}

Check if Extension exists

Check if Extension exists by ID

curl --head https://api.{region}.commercetools.com/{projectKey}/extensions/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if Extension exists by Key

curl --head https://api.{region}.commercetools.com/{projectKey}/extensions/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Check if Extension exists by Query Predicate

curl --head https://api.{region}.commercetools.com/{projectKey}/extensions -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" 

Create Extension

curl https://api.{region}.commercetools.com/{projectKey}/extensions -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "destination" : {
    "type" : "HTTP",
    "url" : "https://example.azurewebsites.net/api/extension",
    "authentication" : {
      "type" : "AzureFunctions",
      "key" : "some-azure-function-code"
    }
  },
  "triggers" : [ {
    "resourceTypeId" : "cart",
    "actions" : [ "Create", "Update" ]
  } ],
  "key" : "my-extension"
}
DATA

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 1,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2017-01-25T14:14:22.417Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-extension"
}

Update Extension

Update Extension by ID

curl https://api.{region}.commercetools.com/{projectKey}/extensions/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setKey",
    "key" : "my-new-extension-key"
  } ]
}
DATA

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 2,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2024-08-06T13:49:48.511Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-new-extension-key"
}

Update Extension by Key

curl https://api.{region}.commercetools.com/{projectKey}/extensions/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "setKey",
    "key" : "my-new-extension-key"
  } ]
}
DATA

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 2,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2024-08-06T13:49:48.511Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-new-extension-key"
}

Update actions

Delete Extension

Delete Extension by ID

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/extensions/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 1,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2017-01-25T14:14:22.417Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-extension"
}

Delete Extension by Key

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/extensions/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

{
  "id": "8062243c-46fc-40b5-88a4-75e2216aef75",
  "version": 1,
  "createdAt": "2017-01-25T14:14:22.417Z",
  "lastModifiedAt": "2017-01-25T14:14:22.417Z",
  "destination": {
    "type": "HTTP",
    "url": "https://example.azurewebsites.net/api/extension",
    "authentication": {
      "type": "AzureFunctions",
      "key": "****code"
    }
  },
  "triggers": [
    {
      "resourceTypeId": "cart",
      "actions": ["Create", "Update"]
    }
  ],
  "key": "my-extension"
}

API Extension within the flow of the API call

The API Extensions are called during the execution of a create or update request. The system first validates that the requested operation can be done, and applies the operation. For example, if an API call requests to add a Product to a Cart, the validation checks that the Product exists and is sold in the country of the Cart, and then adds it to the Cart. However, the result (for example the Cart) is not persisted yet. It is forwarded to the API Extensions, that can run their business logic. API Extension can respond on of three ways:

• If the Extension finds the result to be valid, and does not want to perform any changes, it can return a success. The system will persist the result.
• If the Extension finds that the result is not valid (for example the particular Customer may not purchase this Product), it can return a list of errors. The system will not persist the result and return the errors to the original caller of the API.
• If the Extension wants to perform additional changes, it can return a list of update actions (for example if it wants to add mandatory insurance to the Cart, it can return an AddLineItem update). The system will validate that the update actions are valid for the given resource type and will try to perform the updates. Should that fail, the original caller of the API will receive the errors. Otherwise, the original caller will receive the final result (for example the Cart including the mandatory insurance).

If an API Extension fails to respond properly

In both cases, additional information on the cause of the failure is returned to the original API Client.

In terms of Service Level Agreement (SLA), a failure caused by an API Extension does not count as a failure of the commercetools Composable Commerce API. For example, if an API Extension for the Carts is down and causes downtime for your shop, the SLA won't cover that.

Multiple API Extensions in a single API call

If multiple API Extensions are triggered by an API call, they will be called in parallel. Their responses will be merged, but without a guaranteed order (for example, if two Extensions each return an error, their order in the error list is undefined. If two Extensions return updates, the order in which the updates are performed is undefined).

Responses are merged based on their priority or severity:

• A failure to respond properly by any API Extension will cause the whole request to fail with a 502 or 504.
• Otherwise, if any API Extension finds that the result is not valid, the result will not be persisted and an error will be returned to the original caller of the API.
• Otherwise, if any API Extension returns updates, the result will be modified before it is returned to the original caller of the API.

API Extensions should operate on separate concerns. For example for a Cart, it is fine to have an Extension each for validating that a Customer is allowed to purchase age-restricted Products, calculating shipping costs, and adding mandatory insurance. A counter-example is two API Extensions changing the Price of a Line Item: One for adding extra costs for optional gift wrapping, the other reducing the Price if an externally defined Discount applies - If both Extensions want to change the same Line Item, one will overwrite the result of the other. For this use case, the whole Price calculation for Line Items should be performed inside a single Extension.

You also need to find a balance between clean separation and the increasing latency risk when calling many parallel Extensions.

Input

Headers

• Content-Type - application/json
• X-Correlation-ID - A correlation ID can be used to track a request. The same correlation ID will be returned to the original caller of the API.

Response

An Extension with an AWSLambda destination must return without errors (both for successful responses, and validation failures). Throwing an exception in Java, Python, C# or Go, or invoking the callback with an error in NodeJS, will be treated as a failure to respond properly.

Validation successful / No updates requested

Validation failed

• errors - Array of Error - At least one error must be present.

• responseType - String - "FailedValidation"

Updates requested

• actions - Array of update actions for the resourceType.
  Up to 100 update actions are allowed.

You can use all update actions for the particular resource:

• for cart you can use any Cart update action.
• for order you can use any Order update action.
• for payment you can use any Payment update action.
• for customer you can use any Customer update action.
• for customer-group you can use any Customer Group update action.
• for quote-request you can use any Quote Request update action.
• for staged-quote you can use any Staged Quote update action.
• for quote you can use any Quote update action.
• for business-unit you can use any Business Unit update action B2B.
• for shopping-list you can use any Shopping List update action.

• responseType - String - "UpdateRequest"

Conditional triggers

By default, API Extensions are always called during an update or create action on the resource they are configured for. However, in certain use cases, the Extension should only be triggered when certain conditions are met. Specifying conditional triggers can eliminate unnecessary API calls to your Extension. This eases the load on your service as well as improves overall performance.

• The condition evaluates to true and the API Extension is called.
• The condition evaluates to false, the API Extension is not called.
• The predicate syntax can not be evaluated and the entire API call fails.

Limits and error cases

An API Extension affects the performance and uptime of the API it is extending. Therefore, you should carefully consider the technology used to implement the API Extension and your hosting options.

We believe that deploying an Extension on a Function-as-a-Service is a good fit. You should get a very high up-time and auto-scaling at low costs. However, you should optimize your functions for good cold-start performance.

Time limits

If an API Extension is not responding fast, the whole API call is blocked. We, therefore, enforce the following limits per default:

• An API Extension must return a result within 2 seconds. This includes the network latency.
• For an API Extension with a payment trigger, the time limit can be raised to 10 seconds.
• The commercetools Composable Commerce API must successfully establish a connection to the API Extension within 1 second.

We recommend that your API Extension returns results much faster, though. A good target is to respond within 50 ms.

Error cases

The following errors codes are returned when an API Extension does not respond successfully:

• 400 ExtensionPredicateEvaluationFailed
• 502 ExtensionBadResponse
• 502 ExtensionUpdateActionsFailed
• 504 ExtensionNoResponse