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.

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	Change notifications subscribed to.
`destination` Destination	Messaging service to which the messages are to be sent.
`messages` Array of MessageSubscription	Messages subscribed to.
`format` DeliveryFormat	Format in which the payload is delivered.
`status` SubscriptionHealthStatus	Status of the Subscription.
`createdAt` DateTime	Date and time (UTC) the Subscription was initially created.
`createdBy`BETA CreatedBy	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the Subscription was last modified.
`lastModifiedBy`BETA LastModifiedBy	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: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`changes` Array of ChangeSubscription	Change notifications to be subscribed to.
`destination` Destination	Messaging service to which the messages are sent.
`messages` Array of MessageSubscription	Messages to be subscribed to.
`format` DeliveryFormat	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	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 `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` AwsAuthenticationMode	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.

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

`resourceTypeId` MessageSubscriptionResourceTypeId	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.

resourceTypeId

ChangeSubscriptionResourceTypeId

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` QueryPredicate	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` 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 `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

QueryPredicate

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` Array of SubscriptionUpdateAction	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` Array of SubscriptionUpdateAction	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: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`

Example: json

{
  "action": "setKey",
  "key": "keyString"
}

Set Messages

`action` String	`"setMessages"`
`messages` Array of MessageSubscription	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` 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	Reference to the resource that triggered the message.
`resourceUserProvidedIdentifiers` UserProvidedIdentifiers	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	Reference to the resource that triggered the message.
`resourceUserProvidedIdentifiers` UserProvidedIdentifiers	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` 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` DateTime	Date and time (UTC) the resource was initially created.
`lastModifiedAt` DateTime	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	Reference to the resource that triggered the message.
`resourceUserProvidedIdentifiers` UserProvidedIdentifiers	User-defined unique identifiers of the resource.
`modifiedAt` DateTime	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	Reference to the resource that triggered the message.
`resourceUserProvidedIdentifiers` UserProvidedIdentifiers	User-defined unique identifiers of the resource.
`oldVersion` Int	Version of the resource before the update.
`modifiedAt` DateTime	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	Reference to the resource that triggered the message.
`resourceUserProvidedIdentifiers` UserProvidedIdentifiers	User-defined unique identifiers of the resource.
`modifiedAt` DateTime	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` DateTime	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` DeliveryPayload	MessageDeliveryPayload, ResourceCreatedDeliveryPayload, ResourceUpdatedDeliveryPayload, or ResourceDeletedDeliveryPayload.

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.

Subscriptions for Messages and Notifications

Representations

Subscription

SubscriptionDraft

SubscriptionPagedQueryResponse

Destination

SQSDestination

SNSDestination

EventBridgeDestination

AzureServiceBusDestination

AzureEventGridDestination

GoogleCloudPubSubDestination

ConfluentCloudDestination

AwsAuthenticationMode

MessageSubscription

ChangeSubscription

MessageSubscriptionResourceTypeId

ChangeSubscriptionResourceTypeId

SubscriptionHealthStatus

DeliveryFormat

PlatformFormat

CloudEventsFormat

Get Subscription

Get Subscription by ID

Get Subscription by Key

Get Health Status of Subscription by ID

Query Subscriptions

Check if Subscription exists

Check if Subscription exists by ID

Check if Subscription exists by Key

Check if Subscription exists by Query Predicate

Create Subscription

Update Subscription

Update Subscription by ID

Update Subscription by Key

Update actions

Set Key

Set Messages

Set Changes

Change Destination

Delete Subscription

Delete Subscription by ID

Delete Subscription by Key

Delivery

Delivery payload for the PlatformFormat

MessageDeliveryPayload

PayloadNotIncluded

ResourceCreatedDeliveryPayload

ResourceUpdatedDeliveryPayload

ResourceDeletedDeliveryPayload

Delivery payload for the CloudEventsFormat

Delivery guarantees

At-least-once delivery

No guarantee on order

No guarantee on delivery time