Subscriptions for notifications
Subscriptions send notifications to a message queue of your choice when a Composable Commerce resource is modified.
You can use notifications to trigger asynchronous background processes such as sending an order confirmation email, charging a credit card after an order has shipped, or synchronizing customer accounts to a customer relationship management (CRM) system.
Subscriptions work in the following way:
You create a Subscription and provide details of the message queue, also known as the Destination, where you want to receive the notifications.
When you create, update, or delete a Subscription, it can take up to one minute for the change to take effect. For more information about this, see Eventual Consistency.
Composable Commerce sends a test notification to your queue to make sure the Destination is configured correctly.
When a change occurs to the resource you’ve subscribed to, Composable Commerce sends the notification to the Destination. For information about how we handle the order messages are delivered and our delivery guarantees, see Delivery.
A notification is sent to the Destination as a payload of one of the following types:
- Message - This payload contains one of our predefined Messages.
- Change - This payload contains information about the change to the resource and differs depending on if the resource was created, updated, or deleted.
Your integration uses the notification to trigger your background process.
A maximum of 50
Subscriptions can be created per Project. Learn more about this limit.
Learn more about API Subscriptions in our self-paced Extensibility overview module.
Definitions
Subscription
An integration that sends a notification to your chosen Destination every time there is an addition, a modification, or a deletion in the Composable Commerce resource you subscribe to.
Notification
A payload that informs you of the update to the Composable Commerce resource you subscribed to. A notification can be either a message or a change.
Message
A notification where the payload you receive is one of our predefined Messages.
Change
A notification where the payload contains details of the update to the Composable Commerce resource. The details included in the payload depend on whether the resource was created, updated, or deleted.
Destination
An object containing all the details necessary for Composable Commerce to deliver notifications to your chosen message queue.
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:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
changes Array of ChangeSubscription | Changes subscribed to. |
destination | Messaging service to which the notifications are sent. |
messages Array of MessageSubscription | Messages subscribed to. |
format | Format in which the payload is delivered. |
status | Status of the Subscription. |
createdAt | Date and time (UTC) the Subscription was initially created. |
createdBy BETA | IDs and references that created the Subscription. |
lastModifiedAt | Date and time (UTC) the Subscription was last modified. |
lastModifiedBy BETA | IDs and references that last modified the Subscription. |
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 1,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
changes Array of ChangeSubscription | Changes to be subscribed to. |
destination | Messaging service to which the notifications are sent. |
messages Array of MessageSubscription | Messages to be subscribed to. |
format | Format in which the payload is delivered. When not provided, the PlatformFormat is selected by default. |
{"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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 | Number of results requested. |
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 |
results Array of Subscription | Subscriptions matching the query. |
{"limit": 20,"offset": 0,"count": 1,"total": 1,"results": [{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","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
The API supports the following messaging services:
- AWS SQS, AWS SNS, AWS EventBridge
- Azure Service Bus, Azure Event Grid
- Google Cloud Pub/Sub
- Confluent Cloud
Messaging services are differentiated by the type
field.
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:iam::362576667341:user/subscriptions
. 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 |
accessSecret String | Only present if |
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 |
{"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:iam::362576667341:user/subscriptions
. Otherwise, a test notification 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 |
accessSecret String | Only present if |
topicArn String | Amazon Resource Name (ARN) of the topic. |
authenticationMode | Defines the method of authentication for the SNS topic. Default:Credentials |
{"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. |
source String | URN for the EventBridge destination. |
{"type": "EventBridge","accountId": "<account-id>","region": "<my-region>","source": "aws.partner/commercetools.com/commercetools-project-1/eventbridge"}
AzureServiceBusDestination
Azure Service Bus can be used as a pull-queue with Queues, or to fan-out notifications 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. |
{"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 notifications 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 notifications 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. |
{"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 notification 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. |
{"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 notifications 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 notifications 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 |
apiKey String | Partially hidden on retrieval for security reasons. |
apiSecret String | Partially hidden on retrieval for security reasons. |
acks String | The Kafka "0" , "1" , or "all" |
topic String | The name of the topic. |
{"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 anaccessKey
andaccessSecret
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 notifications to the queue or publish to the topic:arn:aws:iam::362576667341:user/subscriptions
. This is the recommended authentication mode, as it doesn't require additional key management.
MessageSubscription
Messages will be delivered even if the Messages Query HTTP API is not enabled.
For MessageSubscriptions, the format of the payload is MessageDeliveryPayload.
resourceTypeId | Unique identifier for the type of resource, for example, |
types Array of String | Must contain valid message types for the resource. For example, for resource type |
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.
product-tailoring
Messages related to ProductTailoring.
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.
ChangeSubscription
resourceTypeId | Unique identifier for the type of resource, for example, |
ChangeSubscriptionResourceTypeId
Resource types supported by ChangeSubscriptions:
approval-flow
Changes related to ApprovalFlows.
approval-rule
Changes related to ApprovalRules.
associate-role
Changes related to AssociateRoles.
attribute-group
Changes related to AttributeGroups.
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. Modifying Orders via Order Edits does not trigger a notification. To achieve this, a MessageSubscription to the OrderEditApplied Message is necessary.
order-edit
Changes to OrderEdits.
payment
Changes to Payments.
product
Changes to Products.
product-discount
Changes to ProductDiscount.
product-selection
Changes to ProductSelections.
product-tailoring
Changes to ProductTailorings.
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 notifications are being delivered.
Healthy
Delivers notifications as expected.
ConfigurationError
Notifications cannot be delivered with the current configuration. Common causes are deleting the Destination queue, deleting access credentials, or removing necessary permissions. You can fix the configuration by re-creating the configuration on the Destination side, or by setting a new configuration with the Change Destination update action. After the configuration is fixed, undelivered notifications will be delivered and the
status
will change to Healthy.ConfigurationError
is automatically turned intoConfigurationErrorDeliveryStopped
after some time. For more information, see Delivery Guarantees.ConfigurationErrorDeliveryStopped
Does not deliver notifications with the current configuration and the delivery of the notifications is no longer attempted. After the configuration is fixed, undelivered notifications are not retained and will not be delivered. The
status
will change to Healthy as soon as new notifications can be delivered.TemporaryError
Does not deliver notifications temporarily due to reasons other than a configuration error. For example, the Destination has a temporary outage.
ManuallySuspended
Does not deliver notifications with the current configuration and the delivery of the notifications is no longer attempted. Undelivered notifications are not retained and will not be delivered. The
status
will not automatically change to Healthy. To return your subscriptions to a Healthy status, contact the Composable Commerce support team.
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
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 1,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 1,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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
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.
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
Healthy
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
,ConfigurationErrorDeliveryStopped
, andManuallySuspended
503
-TemporaryError
Query Subscriptions
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
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 | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/subscriptions -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"limit": 20,"offset": 0,"count": 1,"total": 1,"results": [{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","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
Checks if a Subscription exists for a given id
. Returns a 200 OK
status if the Subscription exists or a 404 Not Found
otherwise.
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if Subscription exists by 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.
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Check if Subscription exists by Query Predicate
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.
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where |
curl --head https://api.{region}.commercetools.com/{projectKey}/subscriptions -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
Create Subscription
A test notification is sent to ensure the correct configuration of the Destination. If the notification cannot be delivered, the Subscription will not be created. The payload of the test notification is of type ResourceCreated for the resourceTypeId
subscription
.
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
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" : "https://sqs.my-region.amazonaws.com/my-aws-account-number/my-queue","authenticationMode" : "IAM","region" : "my-region"},"messages" : [ {"resourceTypeId" : "product","types" : [ ]} ],"key" : "test-queue"}DATA
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 1,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
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 Array of SubscriptionUpdateAction | Update actions to be performed on the Subscription. |
application/json
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" : "new-key"} ]}DATA
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 2,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/my-queue","authenticationMode": "IAM","region": "my-region"},"messages": [{"resourceTypeId": "product","types": []}],"changes": [],"createdAt": "2017-01-25T14:14:22.417Z","key": "new-key","format": {"type": "Platform"},"lastModifiedAt": "2024-08-06T13:49:48.511Z","status": "Healthy"}
Update Subscription by Key
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
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 Array of SubscriptionUpdateAction | Update actions to be performed on the Subscription. |
application/json
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" : "new-key"} ]}DATA
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 2,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/my-queue","authenticationMode": "IAM","region": "my-region"},"messages": [{"resourceTypeId": "product","types": []}],"changes": [],"createdAt": "2017-01-25T14:14:22.417Z","key": "new-key","format": {"type": "Platform"},"lastModifiedAt": "2024-08-06T13:49:48.511Z","status": "Healthy"}
Update actions
Set Key
action String | "setKey" |
key String | Value to set. If empty, any existing value will be removed. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{"action": "setKey","key": "keyString"}
Set Messages
action String | "setMessages" |
messages Array of MessageSubscription | Value to set. Can only be unset if |
{"action": "setMessages","messages": [{"resourceTypeId": "product","types": ["ProductCreated"]}]}
Set Changes
action String | "setChanges" |
changes Array of ChangeSubscription | Value to set. Can only be unset if |
{"action": "setChanges","changes": [{"resourceTypeId": "channel"},{"resourceTypeId": "product"},{"resourceTypeId": "payment"}]}
Change Destination
A test notification is sent to ensure the correct configuration of the Destination. If the notification cannot be delivered, the update will fail. The payload of the test notification is 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. |
{"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
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
version Int | Last seen version of the resource. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/subscriptions/{id}?version={version} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 1,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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
manage_subscriptions:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
version Int | Last seen version of the resource. |
application/json
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/subscriptions/key={key}?version={version} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"id": "bf79c5d2-2813-4229-9a88-e7c76be50986","version": 1,"destination": {"type": "SQS","queueUrl": "https://sqs.my-region.amazonaws.com/my-aws-account-number/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 |
|
notificationType String | Identifies the payload. |
resource | Reference to the resource that triggered the notification. |
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 |
|
notificationType String | "Message" Identifies the payload. |
resource | Reference to the resource that triggered the notification. |
resourceUserProvidedIdentifiers | User-defined unique identifiers of the resource. |
sequenceNumber Int | Used to ensure all messages of the resource are processed in correct order.
The |
resourceVersion Int | Version of the resource on which the update was performed. |
payloadNotIncluded | If the payload does not fit into the size limit or its format is not accepted by the messaging service, the |
createdAt | Date and time (UTC) the resource was initially created. |
lastModifiedAt | Date and time (UTC) the resource was last modified. |
{"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 does not fit inside the limit, 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 |
{"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 |
|
notificationType String | "ResourceCreated" Identifies the payload. |
resource | Reference to the resource that triggered the notification. |
resourceUserProvidedIdentifiers | User-defined unique identifiers of the resource. |
modifiedAt | Date and time (UTC) the resource was last modified. |
{"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 |
|
notificationType String | "ResourceUpdated" Identifies the payload. |
resource | Reference to the resource that triggered the notification. |
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. |
{"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 |
|
notificationType String | "ResourceDeleted" Identifies the payload. |
resource | Reference to the resource that triggered the notification. |
resourceUserProvidedIdentifiers | User-defined unique identifiers of the resource. |
modifiedAt | Date and time (UTC) the resource was last deleted. |
dataErasure Boolean |
|
{"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 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 |
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 |
sequence String | Corresponds to the |
sequencetype String |
|
dataref String | The URI from which the message can be retrieved if messages are enabled. Only set for MessageSubscriptions. |
data |
{"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 a notification has been accepted by the Destination, it will retry the delivery. Our Retry Policy depends on the SubscriptionHealthStatus:
TemporaryError
- Retry for up to 48 hours, after which notifications 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 toConfigurationErrorDeliveryStopped
, and notifications are dropped.
A side effect of the retry is that the same notification may be sent several times. An idempotent processor that doesn't process the same notification twice can check whether it 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 notification payloads we attempt to deliver to a Destination are valid according to their specification. Therefore, the only cases where notifications can't 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
Notifications 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 notification processor can use the fields resource.id
and sequenceNumber
to process notifications in the correct order (for example, if the last processed sequenceNumber
was 2
, and the current notification is 4
, the current notification can be put back into the queue for processing at a later point in time).
For notifications 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
Notifications are not guaranteed to be delivered within a certain time frame. Although most notifications 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.