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:

  1. 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.

  2. Composable Commerce sends a test notification to your queue to make sure the Destination is configured correctly.

  3. 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.
  4. 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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
changes
Array of ChangeSubscription

Changes subscribed to.

destination

Messaging service to which the notifications are 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

IDs and references that created the Subscription.

lastModifiedAt

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

lastModifiedByBETA

IDs and references that last modified the Subscription.

Example: json
{
"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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
changes
Array of ChangeSubscription

Changes to be subscribed to.

destination

Messaging service to which the notifications 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": "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
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": "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:

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 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: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 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.

source
String

URN for the EventBridge destination.

Example: json
{
"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.

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 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.

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 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.

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 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 <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 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.

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.

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

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.

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 into ConfigurationErrorDeliveryStopped 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

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": "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

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": "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

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, ConfigurationErrorDeliveryStopped, and ManuallySuspended
  • 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.

Default: true
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": "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

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 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.

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" : "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
201 Response Example: Subscriptionjson
{
"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

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" : "new-key"
} ]
}
DATA
200 Response Example: Subscriptionjson
{
"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

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" : "new-key"
} ]
}
DATA
200 Response Example: Subscriptionjson
{
"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: 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 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.

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": "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

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": "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

key of the Project. Useful for processing notifications if the Destination receives them from multiple Projects.

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

key of the Project. Useful for processing notifications if the Destination receives them from multiple Projects.

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 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 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 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 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 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 for processing notifications if the Destination receives them from multiple Projects.

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.

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 for processing notifications if the Destination receives them from multiple Projects.

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.

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 for processing notifications if the Destination receives them from multiple Projects.

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

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 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 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 to ConfigurationErrorDeliveryStopped, 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.