This is the early access documentation preview for Custom Views. This documentation might not be in sync with our official documentation.

Subscriptions for Messages and Notifications

Subscriptions allow you to be notified of new messages or changes via a message queue of your choice.

Subscriptions are used to trigger an asynchronous background process in response to an event on commercetools Composable Commerce. Common use cases include sending an order confirmation email, charging a credit card after a delivery has been made, or synchronizing customer accounts to a Customer Relationship Management (CRM) system.

As payload, a Subscription delivers one of the predefined Messages or a notification about a change to a resource.

A maximum of 50 Subscriptions can be created per Project. Learn more about this limit.

When you create, update, or delete Subscriptions, it may take up to a minute for the changes to update. For more information, see Eventual Consistency.

This document explains the creation of a Subscription, the payload, and delivery guarantees.

Learn more about API Subscriptions in our self-paced Extensibility overview module.

Representations

Subscription

id
String

Unique identifier of the Subscription.

version
Int

Current version of the Subscription.

key
String

User-defined unique identifier of the Subscription.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
changes
Array of ChangeSubscription

Change notifications subscribed to.

destination

Messaging service to which the messages are to be sent.

messages

Messages subscribed to.

format

Format in which the payload is delivered.

Status of the Subscription.

createdAt

Date and time (UTC) the Subscription was initially created.

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

Date and time (UTC) the Subscription was last modified.

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

Example: json
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

SubscriptionDraft

Either messages or changes must be set.

key
String

User-defined unique identifier for the Subscription.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
changes
Array of ChangeSubscription

Change notifications to be subscribed to.

destination

Messaging service to which the messages are sent.

messages

Messages to be subscribed to.

format

Format in which the payload is delivered. When not provided, the PlatformFormat is selected by default.

Example: json
{
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"key": "test-queue"
}

SubscriptionPagedQueryResponse

PagedQueryResult with results containing an array of Subscription.

limit
Int
offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

results
Array of Subscription

Subscriptions matching the query.

Example: json
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}
]
}

Destination

A Destination contains all information necessary for Composable Commerce to deliver messages to your messaging service. Supported messaging services are differentiated by the type field.

The API supports the following messaging services:

SQSDestination

AWS SQS is a pull-queue on AWS. The queue must be a Standard queue type with a MaximumMessageSize of 256 KB.

We recommend setting authenticationMode to IAM, to avoid unnecessary key management. For IAM authentication and before creating the Subscription, give permissions to the following user account: arn:aws-cn:iam::417094354346:user/subscriptions if the Project is hosted in the China (AWS, Ningxia) Region; arn:aws:iam::362576667341:user/subscriptions for all other Regions. Otherwise, a test message will not be sent.

If you prefer to use Credentials for authentication, we recommend creating an IAM user with an accessKey and accessSecret pair specifically for each Subscription.

The IAM user should only have the sqs:SendMessage permission on this queue.

type
String
"SQS"
accessKey
String

Only present if authenticationMode is set to Credentials.

accessSecret
String

Only present if authenticationMode is set to Credentials.

queueUrl
String

URL of the Amazon SQS queue.

region
String

AWS Region the message queue is located in.

authenticationMode

Defines the method of authentication for the SQS queue.

Default: Credentials
Example: json
{
"type": "SQS",
"queueUrl": "https://sqs.<my-region>.amazonaws.com/<my-aws-account-number>/<my-queue>",
"accessKey": "<my-access-key>",
"accessSecret": "<my-access-secret>",
"region": "<my-region>",
"authenticationMode": "Credentials"
}

SNSDestination

AWS SNS can be used to push messages to AWS Lambda, HTTP endpoints (webhooks), or fan-out messages to SQS queues. The SQS queue must be a Standard queue type.

We recommend setting authenticationMode to IAM, to avoid unnecessary key management. For IAM authentication and before creating the Subscription, give permissions to the following user account: arn:aws-cn:iam::417094354346:user/subscriptions if the Project is hosted in the China (AWS, Ningxia) Region; arn:aws:iam::362576667341:user/subscriptions for all other Regions. Otherwise, a test message will not be sent.

If you prefer to use Credentials for authentication, we recommend creating an IAM user with an accessKey and accessSecret pair specifically for each Subscription.

The IAM user should only have the sns:Publish permission on this topic.

type
String
"SNS"
accessKey
String

Only present if authenticationMode is set to Credentials.

accessSecret
String

Only present if authenticationMode is set to Credentials.

topicArn
String

Amazon Resource Name (ARN) of the topic.

authenticationMode

Defines the method of authentication for the SNS topic.

Default: Credentials
Example: json
{
"type": "SNS",
"accessKey": "<my-access-key>",
"accessSecret": "<my-access-secret>",
"topicArn": "arn:aws:sns:<my-region>:<topic>",
"authenticationMode": "Credentials"
}

EventBridgeDestination

AWS EventBridge can be used to push events and messages to a serverless event bus that can forward them to AWS SQS, SNS, Lambda, and other AWS services based on forwarding rules. Once the Subscription is created, an equivalent "partner event source" is created in AWS EventBridge. This event source must be associated with an event bus for the Subscription setup to be complete.

type
String
"EventBridge"
region
String

AWS region that receives the events.

accountId
String

ID of the AWS account that receives the events.

Example: json
{
"type": "EventBridge",
"accountId": "<account-id>",
"region": "<my-region>"
}

AzureServiceBusDestination

Azure Service Bus can be used as a pull-queue with Queues, or to fan-out messages with Topics and Subscriptions. To set up a Subscription with Azure Service Bus, first create a queue/topic in the Azure Portal with a Shared Access Policy including the Send permission.

type
String
"AzureServiceBus"
connectionString
String

SharedAccessKey is partially hidden on retrieval for security reasons.

Example: json
{
"type": "AzureServiceBus",
"connectionString": "<connection-string>"
}

To grant access to resources, Azure Service Bus uses the concept of Shared Access Policies. Shared Access Policy is defined on a scope and includes certain permissions. For setting up an Azure Service Bus Subscription on Composable Commerce, you must create a Shared Access Policy on your queue/topic and include the Send permission. When you open the policy in the Azure Portal, you will find that Azure has generated two connection strings for your policy. A connection string has the following format:

Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>

You can set either of the two connection strings in the connectionString attribute of an Azure Service Bus Destination. Ensure that the path points to your queue/topic.

AzureEventGridDestination

Azure Event Grid can be used to push messages to Azure Functions, HTTP endpoints (webhooks), and several other Azure tools. Event Grid can only be used with the CloudEventsFormat. To set up a Subscription with Azure Event Grid, first create a topic in the Azure Portal. To allow Composable Commerce to push messages to your topic, provide an access key.

type
String
"EventGrid"
uri
String

URI of the topic.

accessKey
String

Partially hidden on retrieval for security reasons.

Example: json
{
"type": "EventGrid",
"uri": "<my-uri>",
"accessKey": "<my-access-key>"
}

GoogleCloudPubSubDestination

Destination for Google Cloud Pub/Sub that can be used for Pull subscriptions as well as for Push subscriptions. The topic must give the pubsub.topics.publish permission to the service account subscriptions@commercetools-platform.iam.gserviceaccount.com. If used with the CloudEventsFormat, the message conforms to the PubSub Protocol Binding of the Structured Content Mode.

type
String
"GoogleCloudPubSub"
projectId
String

ID of the Google Cloud project that contains the Pub/Sub topic.

topic
String

Name of the topic.

Example: json
{
"type": "GoogleCloudPubSub",
"topic": "Topic",
"projectId": "<project-id>"
}

commercetools Projects hosted on Google Cloud can benefit from additional security by enabling Google Cloud's VPC Service Controls. This ensures that Google Cloud Pub/Sub Destinations can only be accessed from the commercetools Google Cloud infrastructure.

To configure VPC Service Controls, specify the commercetools GCP project number as the source of your ingress policy rule. You can optionally select subscriptions@commercetools-platform.iam.gserviceaccount.com as the identity of the ingress policy for an added layer of security. To obtain the required commercetools GCP project number, contact your Customer Success Manager.

ConfluentCloudDestination

This destination can be used to push events and messages to Confluent Cloud. To set up a Subscription of this type, first, create a topic in Confluent Cloud. Then, to allow Composable Commerce to push events and messages to your topic, generate API keys for your topic, and create the Subscription destination using the generated credentials.

The Composable Commerce producer uses the following values: SASL_SSL forsecurity.protocol, PLAIN forsasl.mechanism, and the default value (1048576) for max.request.size.

key
String

The Kafka record key.

type
String
"ConfluentCloud"
bootstrapServer
String

URL to the bootstrap server including the port number in the format <xxxxx>.<region>.<provider>.confluent.cloud:9092.

apiKey
String

Partially hidden on retrieval for security reasons.

apiSecret
String

Partially hidden on retrieval for security reasons.

acks
String

The Kafka acks value.

Can be "0", "1", or "all"
topic
String

The name of the topic.

Example: json
{
"type": "ConfluentCloud",
"bootstrapServer": "<my-bootstrap-server-url>",
"apiKey": "<my-api-key>",
"apiSecret": "<my-api-secret>",
"acks": "1",
"topic": "<my-topic-name>",
"key": "<my-kafka-record-key>"
}

AwsAuthenticationMode

Defines the method of authentication for AWS SQS and SNS Destinations.

Credentials

Subscriptions with Credentials authentication mode are authenticated using an accessKey and accessSecret pair. This is the default authentication mode for backwards compatibility.

IAM

Subscriptions with IAM authentication mode are authenticated using Identity and Access Management (IAM). For this authentication mode, the following user requires permissions to send messages to the queue or publish to the topic: arn:aws-cn:iam::417094354346:user/subscriptions if the Project is hosted in the China (AWS, Ningxia) Region; arn:aws:iam::362576667341:user/subscriptions for all other Regions. This is the recommended authentication mode, as it doesn't require additional key management.

MessageSubscription

For supported resources and message types, see Message Types. Messages will be delivered even if the Messages Query HTTP API is not enabled.

For MessageSubscriptions, the format of the payload is MessageDeliveryPayload.

Unique identifier for the type of resource, for example, order.

types
Array of String

Must contain valid message types for the resource. For example, for resource type product the message type ProductPublished is valid. If no types of messages are given, the Subscription will receive all messages for this resource.

ChangeSubscription

Notification about changes to a resource. The payload format differs for resource creation, update, and deletion.

Unique identifier for the type of resource, for example, cart.

MessageSubscriptionResourceTypeId

Resource types supported by MessageSubscriptions:

approval-flow

Messages related to ApprovalFlows.

approval-rule

Messages related to ApprovalRules.

associate-role

Messages related to AssociateRoles.

business-unit

Messages related to BusinessUnits.

category

Messages related to Categories.

customer

Messages related to Customers.

customer-email-token

Messages related to CustomerTokens for email verification.

customer-group

Messages related to CustomerGroups.

customer-password-token

Messages related to CustomerTokens for password reset.

inventory-entry

Messages related to InventoryEntries.

order

Messages related to Orders.

payment

Messages related to Payments.

product

Messages related to Products.

product-selection

Messages related to ProductSelections.

quote

Messages related to Quotes.

quote-request

Messages related to Quote Requests.

review

Messages related to Reviews.

staged-quote

Messages related to Staged Quotes.

standalone-price

Messages related to StandalonePrices.

store

Messages related to Stores.

ChangeSubscriptionResourceTypeId

Resource types supported by ChangeSubscriptions:

approval-flow

Changes related to ApprovalFlows.

approval-rule

Changes related to ApprovalRules.

associate-role

Changes related to AssociateRoles.

business-unit

Changes to BusinessUnits.

cart

Changes to Carts.

cart-discount

Changes to CartDiscounts.

category

Changes to Categories.

channel

Changes to Channels.

customer

Changes to Customers.

customer-email-token

Changes to CustomerTokens.

customer-group

Changes to CustomerGroups.

customer-password-token

Changes to CustomerTokens.

discount-code

Changes to DiscountCodes.

extension

Changes to Extensions.

inventory-entry

Changes to InventoryEntries.

key-value-document

Changes to CustomObjects.

order

Changes to Orders. Changes to Orders via Order Edits do not trigger a Message. To achieve this, a MessageSubscription to OrderEditApplied Message is necessary.

order-edit

Changes to OrderEdits.

payment

Changes to Payments.

product

Changes to Products.

product-discount

Changes to ProductDiscount.

product-price

Changes to EmbeddedPrices.

product-selection

Changes to ProductSelections.

product-type

Changes to ProductTypes.

quote

Changes to Quotes.

quote-request

Changes to QuoteRequests.

review

Changes to Reviews.

shipping-method

Changes to ShippingMethods.

shopping-list

Changes to ShoppingLists.

staged-quote

Changes to StagedQuotes.

standalone-price

Changes to StandalonePrices.

state

Changes to States.

store

Changes to Stores.

subscription

Changes to Subscriptions.

tax-category

Changes to TaxCategories.

type

Changes to Types.

zone

Changes to Zones.

SubscriptionHealthStatus

The health status of the Subscription that indicates whether messages are being delivered to the Destination.

Healthy

Delivers messages as expected.

ConfigurationError

Messages cannot be delivered with the current configuration. Common causes are deleting the Destination queue, deleting access credentials, or removing the necessary permissions. The configuration can be fixed by re-creating the configuration on the Destination side, or by setting a new configuration with the Change Destination update action. If the configuration is fixed, undelivered messages will be delivered and the status will change to Healthy. ConfigurationError is automatically turned into ConfigurationErrorDeliveryStopped after some time. For more information, see Delivery Guarantees.

ConfigurationErrorDeliveryStopped

Does not deliver messages with the current configuration and the delivery of the messages is no longer attempted. If the configuration is fixed, undelivered messages are not retained and will not be delivered. The status will change to Healthy as soon as new messages can be delivered.

TemporaryError

Does not deliver messages temporarily due to reasons other than a configuration error. For example, the Destination has a temporary outage.

The health of the delivery infrastructure is independent of the SubscriptionHealthStatus and can be checked on the status page.

DeliveryFormat

The format in which the payload is delivered. Defaults to PlatformFormat.

PlatformFormat

The PlatformFormat uses constructs that are similar to the ones used in the REST API, for example, on the Messages Query HTTP API.

type
String
"Platform"

CloudEventsFormat

The CloudEventsFormat can be used with any Destination, and the payload is delivered in the JSON Event Format. AzureEventGridDestination offers native support to filter and route CloudEvents.

type
String
"CloudEvents"
cloudEventsVersion
String
"1.0"

Get Subscription

Get Subscription by ID

GET
https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Subscription.

Response:
200Subscriptionasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Get Subscription by Key

GET
https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key}
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Subscription.

Response:
200Subscriptionasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Get Health Status of Subscription by ID

GET
https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}/health

This endpoint can be polled by a monitoring or alerting system that checks the health of your Subscriptions. To ease integration with such systems this endpoint does not require Authorization.

Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Subscription.

Response:
200

Healthy

Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}/health -i

The HTTP status codes are mapped to the SubscriptionHealthStatus as follows:

  • 200 - Healthy
  • 400 - ConfigurationError and ConfigurationErrorDeliveryStopped
  • 503 - TemporaryError

Query Subscriptions

GET
https://api.{region}.commercetools.com/{projectKey}/subscriptions
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

withTotal
Boolean

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200SubscriptionPagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: SubscriptionPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}
]
}

Check if Subscription exists

Check if Subscription exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}

Checks if a Subscription exists for a given id. Returns a 200 OK status if the Subscription exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Subscription.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Subscription exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key}

Checks if a Subscription exists for a given key. Returns a 200 OK status if the Subscription exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Subscription.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if Subscription exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/subscriptions

Checks if a Subscription exists for a given Query Predicate. Returns a 200 OK status if any Subscriptions match the Query Predicate or a 404 Not Found otherwise.

OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where

Query Predicates on Subscriptions are limited to Text, Enum, Boolean, Number, Date, Time, and DateTime attribute types.

The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/subscriptions -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Subscription

POST
https://api.{region}.commercetools.com/{projectKey}/subscriptions

A test message is sent to ensure the correct configuration of the Destination. If the message cannot be delivered, the Subscription will not be created. The payload of the test message is a notification of type ResourceCreated for the resourceTypeId subscription.

OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Request Body:SubscriptionDraftasapplication/json
Response:
201Subscriptionasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/subscriptions -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"destination" : {
"type" : "SQS",
"queueUrl" : "<url-to-my-queue>",
"authenticationMode" : "IAM",
"region" : "<my-region>"
},
"messages" : [ {
"resourceTypeId" : "product",
"types" : [ ]
} ],
"key" : "test-queue"
}
DATA
201 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Update Subscription

Update Subscription by ID

POST
https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Subscription.

Request Body:
application/json
version
Int

Expected version of the Subscription on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the Subscription.

Response:
200Subscriptionasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setKey",
"key" : "queue-key"
} ]
}
DATA
200 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Update Subscription by Key

POST
https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key}
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Subscription.

Request Body:
application/json
version
Int

Expected version of the Subscription on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.

actions

Update actions to be performed on the Subscription.

Response:
200Subscriptionasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"version" : 1,
"actions" : [ {
"action" : "setKey",
"key" : "queue-key"
} ]
}
DATA
200 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Update actions

Set Key

action
String
"setKey"
key
String

Value to set. If empty, any existing value will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action": "setKey",
"key": "keyString"
}

Set Messages

action
String
"setMessages"
messages

Value to set. Can only be unset if changes is set.

Example: json
{
"action": "setMessages",
"messages": [
{
"resourceTypeId": "product",
"types": ["ProductCreated"]
}
]
}

Set Changes

action
String
"setChanges"
changes
Array of ChangeSubscription

Value to set. Can only be unset if messages is set.

Example: json
{
"action": "setChanges",
"changes": [
{
"resourceTypeId": "channel"
},
{
"resourceTypeId": "product"
},
{
"resourceTypeId": "payment"
}
]
}

Change Destination

A test message is sent to ensure the correct configuration of the Destination. If the message cannot be delivered, the update will fail. The payload of the test message is a notification of type ResourceCreated for the resourceTypeId subscription. The status will change to Healthy, if it isn't already.

action
String
"changeDestination"
destination

New value to set. Must not be empty.

Example: json
{
"action": "changeDestination",
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"accessKey": "<my-access-key>",
"accessSecret": "<my-access-secret>",
"region": "<my-region>",
"authenticationMode": "Credentials"
}
}

Delete Subscription

Delete Subscription by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Subscription.

Query parameters:
version
Int

Last seen version of the resource.

Response:
200Subscriptionasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Delete Subscription by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key}
OAuth 2.0 Scopes:
manage_subscriptions:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Subscription.

Query parameters:
version
Int

Last seen version of the resource.

Response:
200Subscriptionasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: Subscriptionjson
{
"id": "8062243c-46fc-40b5-88a4-75e2216aef75",
"version": 1,
"destination": {
"type": "SQS",
"queueUrl": "<url-to-my-queue>",
"authenticationMode": "IAM",
"region": "<my-region>"
},
"messages": [
{
"resourceTypeId": "product",
"types": []
}
],
"changes": [],
"createdAt": "2017-01-25T14:14:22.417Z",
"key": "test-queue",
"format": {
"type": "Platform"
},
"lastModifiedAt": "2017-01-25T14:14:22.417Z",
"status": "Healthy"
}

Delivery

The Delivery payload depends on the chosen DeliveryFormat.

Delivery payload for the PlatformFormat

All payloads for the PlatformFormat share these common fields.

projectKey
String

key of the Project. Useful in message processing if the Destination receives events from multiple Projects.

notificationType
String

Identifies the payload.

resource

Reference to the resource that triggered the message.

resourceUserProvidedIdentifiers

User-defined unique identifiers of the resource.

MessageDeliveryPayload

This payload is sent for a MessageSubscription.

id
String

Unique ID of the message.

version
Int

Last seen version of the resource.

projectKey
String

key of the Project. Useful in message processing if the Destination receives events from multiple Projects.

notificationType
String
"Message"

Identifies the payload.

resource

Reference to the resource that triggered the message.

resourceUserProvidedIdentifiers

User-defined unique identifiers of the resource.

sequenceNumber
Int

Used to ensure all messages of the resource are processed in correct order. The sequenceNumber of the next message of the resource is a successor of the sequenceNumber of the current message.

resourceVersion
Int

Version of the resource on which the change was performed.

payloadNotIncluded

If the payload does not fit into the size limit or its format is not accepted by the messaging service, the payloadNotIncluded field is present.

createdAt

Date and time (UTC) the resource was initially created.

lastModifiedAt

Date and time (UTC) the resource was last modified.

Example: json
{
"notificationType": "Message",
"projectKey": "<project_key>",
"id": "<message_id>",
"version": 1,
"sequenceNumber": 2,
"resource": {
"typeId": "customer",
"id": "<customer_id>"
},
"resourceVersion": 2,
"resourceUserProvidedIdentifiers": {},
"type": "CustomerLastNameSet",
"lastName": "Doe",
"createdAt": "2022-10-25T13:30:09.760Z",
"lastModifiedAt": "2022-10-25T13:30:09.760Z"
}

If the payload fits into the size limit of your message queue (the limit is often 256 KB), all additional fields for the specific message are included as well (along with the type field). If the payload did not fit inside the message, it can be retrieved from the Messages Query HTTP API if the feature is enabled.

PayloadNotIncluded

reason
String

Reason the payload is not included. For example, the payload is too large, or its content is not supported by the Subscription destination.

payloadType
String

Value of the type field in the original payload.

Example: json
{
"reason": "Payload too large.",
"payloadType": "ProductPublished"
}

ResourceCreatedDeliveryPayload

This payload is sent for a ChangeSubscription when a resource is created.

version
Int

Last seen version of the resource.

projectKey
String

key of the Project. Useful in message processing if the Destination receives events from multiple Projects.

notificationType
String
"ResourceCreated"

Identifies the payload.

resource

Reference to the resource that triggered the message.

resourceUserProvidedIdentifiers

User-defined unique identifiers of the resource.

modifiedAt

Date and time (UTC) the resource was last modified.

Example: json
{
"notificationType": "ResourceCreated",
"projectKey": "<project_key>",
"resource": {
"typeId": "product",
"id": "<product_id>"
},
"resourceUserProvidedIdentifiers": {
"key": "example-product-key",
"slug": {
"en": "example-slug"
}
},
"version": 1,
"modifiedAt": "2022-10-25T13:23:05.384Z"
}

ResourceUpdatedDeliveryPayload

This payload is sent for a ChangeSubscription when a resource is updated. This includes updates by a background process, like a change in product availability.

version
Int

Last seen version of the resource.

projectKey
String

key of the Project. Useful in message processing if the Destination receives events from multiple Projects.

notificationType
String
"ResourceUpdated"

Identifies the payload.

resource

Reference to the resource that triggered the message.

resourceUserProvidedIdentifiers

User-defined unique identifiers of the resource.

oldVersion
Int

Version of the resource before the update.

modifiedAt

Date and time (UTC) the resource was last updated.

Example: json
{
"notificationType": "ResourceUpdated",
"projectKey": "<project-key>",
"resource": {
"typeId": "product",
"id": "<product-id>"
},
"resourceUserProvidedIdentifiers": {
"key": "example-product-key",
"slug": {
"en": "example-product-slug"
}
},
"version": 3,
"oldVersion": 1,
"modifiedAt": "2022-10-25T13:23:40.577Z"
}

ResourceDeletedDeliveryPayload

This payload is sent for a ChangeSubscription when a resource is deleted.

version
Int

Last seen version of the resource.

projectKey
String

key of the Project. Useful in message processing if the Destination receives events from multiple Projects.

notificationType
String
"ResourceDeleted"

Identifies the payload.

resource

Reference to the resource that triggered the message.

resourceUserProvidedIdentifiers

User-defined unique identifiers of the resource.

modifiedAt

Date and time (UTC) the resource was last deleted.

dataErasure
Boolean

true if the dataErasure parameter on the DELETE request was set to true.

Example: json
{
"notificationType": "ResourceDeleted",
"projectKey": "<project-key>",
"resource": {
"typeId": "product",
"id": "<product-id>"
},
"resourceUserProvidedIdentifiers": {
"key": "example-product-key",
"slug": {
"en": "example-product-slug"
}
},
"version": 3,
"modifiedAt": "2022-10-25T13:23:50.113Z"
}

Delivery payload for the CloudEventsFormat

The CloudEventsFormat represents event data in a way that conforms to a common specification. The message payload can be found inside the data field.

id
String

Unique identifier of the event.

specversion
String

The version of the CloudEvents specification which the event uses.

type
String

The type is namespaced with com.commercetools, followed by the ReferenceTypeId, the type of Subscription (either message or change), and the message or change type. For example, com.commercetools.product.message.ProductPublished or com.commercetools.order.change.ResourceCreated.

source
String

The default REST URI of the ReferenceTypeId that triggered this event, including the project key.

subject
String

Unique identifier of the resource that triggered the event.

time

Corresponds to the lastModifiedAt of the resource at the time the event was triggered.

sequence
String

Corresponds to the sequenceNumber of a MessageSubscription. Can be used to process messages in the correct order.

sequencetype
String

"Integer"

dataref
String

The URI from which the message can be retrieved if messages are enabled. Only set for MessageSubscriptions.

data
Example: json
{
"id": "81ee6da8-5bc2-471b-9159-89bac735a45d",
"source": "/<project_key>/products",
"specversion": "1.0",
"type": "com.commercetools.product.message.ProductPublished",
"subject": "b32d1013-cd25-4cb4-95ab-99c494531d73",
"time": "2022-06-17T08:41:58.066Z",
"dataref": "/<project-key>/messages/81ee6da8-5bc2-471b-9159-89bac735a45d",
"sequence": "2",
"sequencetype": "Integer",
"data": {
"notificationType": "Message",
"projectKey": "<project-key>",
"id": "81ee6da8-5bc2-471b-9159-89bac735a45d",
"version": 1,
"sequenceNumber": 2,
"resource": {
"typeId": "product",
"id": "b32d1013-cd25-4cb4-95ab-99c494531d73"
},
"resourceVersion": 2,
"resourceUserProvidedIdentifiers": {
"key": "product-key-1",
"slug": {
"en": "product-slug-1"
}
},
"type": "ProductPublished",
"productProjection": {
"id": "b32d1013-cd25-4cb4-95ab-99c494531d73",
"version": 2,
"productType": {
"typeId": "product-type",
"id": "25ef7088-74dd-4b92-bf3c-705dfa20deaa"
},
"categories": [],
"hasStagedChanges": false,
"published": true,
"key": "product-key-1",
"createdAt": "2022-06-17T08:21:40.279Z",
"lastModifiedAt": "2022-06-17T08:41:58.066Z"
},
"removedImageUrls": [],
"scope": "All",
"createdAt": "2022-06-17T08:41:58.066Z",
"lastModifiedAt": "2022-06-17T08:41:58.066Z"
}
}

Delivery guarantees

At-least-once delivery

If Composable Commerce did not get a positive acknowledgment that messages have been accepted by the Destination, it will retry the message delivery. Our Retry Policy depends on the SubscriptionHealthStatus:

  • TemporaryError - Retry for up to 48 hours, after which messages may be dropped.
  • ConfigurationError - Retry for up to 24 hours (for production Projects) or 1 hour (for development or staging Projects), after which the status changes to ConfigurationErrorDeliveryStopped, and messages are dropped.

A side effect of the retry is that the same message may be sent several times. An idempotent message processor that doesn't process the same message twice can check whether the message was already processed. For notificationType "Message", use the fields resource.id and sequenceNumber. In other cases, use the field's resource.id and version.

We guarantee that all message payloads we attempt to deliver to a Destination are valid according to their specification. Therefore, the only cases where messages can not be delivered are due to an ongoing incident, or due to a misconfiguration.

You can monitor the health of a Subscription with a tool of your choice. For production-critical queues, we recommend setting up an automatic alert.

No guarantee on order

Messages are not guaranteed to be delivered in their natural order (for example, with ascending sequenceNumber or ascending version). This is especially true in the case of retries.

For notificationType "Message", a message processor can use the fields resource.id and sequenceNumber to process messages in the correct order (for example, if the last processed sequenceNumber was 2, and the current message is 4, the current message can be put back into the queue for processing at a later point in time).

For messages of notificationType other than "Message", the fields resource.id, version and (in case of update) oldVersion can be used. Note that version is not sequential.

No guarantee on delivery time

Messages are not guaranteed to be delivered within a certain time frame. Although most messages are delivered within seconds, delays of several minutes can be caused by a variety of factors, such as scaling infrastructure resources. Therefore we do not recommend using Subscriptions for time-critical use cases where a few minute's delay is seen as an incident.