# Subscriptions for notifications Subscriptions send notifications to a message queue of your choice when a 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](https://docs.commercetools.com/api/general-concepts.md#eventual-consistency). 2. The API 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, the API sends the notification to the Destination. For information about how we handle the order messages are delivered and our delivery guarantees, see [Delivery](https://docs.commercetools.com/api/projects/subscriptions.md#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](https://docs.commercetools.com/api/projects/messages.md). - Change - This payload contains information about the [change to the resource](https://docs.commercetools.com/api/projects/subscriptions.md#changesubscription) and differs depending on if the resource was created, updated, or deleted. - Event - This payload contains one of our predefined [Events](https://docs.commercetools.com/api/events.md). 4. Your integration uses the notification to trigger your background process. A maximum of 50 Subscriptions can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See [Limit increase guidance](https://docs.commercetools.com/api/limit-increase-guidance.md#extensibility-and-eventing-limits). Learn more about API Subscriptions in our self-paced Extensibility overview and Integration patterns modules. ## Representations #### Subscription See API type definition [Subscription](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscription). #### SubscriptionDraft See API type definition [SubscriptionDraft](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionDraft). #### SubscriptionPagedQueryResponse See API type definition [SubscriptionPagedQueryResponse](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionPagedQueryResponse). #### Destination The API supports the following messaging services: - [AWS SQS](https://aws.amazon.com/sqs/), [AWS SNS](https://aws.amazon.com/sns/), [AWS EventBridge](https://aws.amazon.com/eventbridge/) - [Azure Service Bus](https://azure.microsoft.com/en-us/products/service-bus/), [Azure Event Grid](https://azure.microsoft.com/en-us/products/event-grid/) - [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/) - [Confluent Cloud](https://www.confluent.io/confluent-cloud/) Messaging services are differentiated by the `type` field. ##### SQSDestination See API type definition [SqsDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASqsDestination). ##### SNSDestination See API type definition [SnsDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASnsDestination). ##### EventBridgeDestination See API type definition [EventBridgeDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AEventBridgeDestination). ##### AzureServiceBusDestination See API type definition [AzureServiceBusDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AAzureServiceBusDestination). To grant access to resources, Azure Service Bus uses the concept of [Shared Access Policies](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-sas). Shared Access Policy is defined on a scope and includes certain permissions. For setting up an Azure Service Bus Subscription, 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://.servicebus.windows.net/;SharedAccessKeyName=;SharedAccessKey=;EntityPath=` 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 See API type definition [AzureEventGridDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AAzureEventGridDestination). ##### GoogleCloudPubSubDestination See API type definition [GoogleCloudPubSubDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AGoogleCloudPubSubDestination). commercetools Projects hosted on Google Cloud can benefit from additional security by enabling [Google Cloud's VPC Service Controls](https://cloud.google.com/security/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 See API type definition [ConfluentCloudDestination](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AConfluentCloudDestination). #### AwsAuthenticationMode See API type definition [AwsAuthenticationMode](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AAwsAuthenticationMode). #### MessageSubscription See API type definition [MessageSubscription](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AMessageSubscription). ##### MessageSubscriptionResourceTypeId See API type definition [MessageSubscriptionResourceTypeId](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AMessageSubscriptionResourceTypeId). #### ChangeSubscription See API type definition [ChangeSubscription](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AChangeSubscription). ##### ChangeSubscriptionResourceTypeId See API type definition [ChangeSubscriptionResourceTypeId](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AChangeSubscriptionResourceTypeId). #### EventSubscription See API type definition [EventSubscription](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AEventSubscription). ##### EventSubscriptionResourceTypeId See API type definition [EventSubscriptionResourceTypeId](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AEventSubscriptionResourceTypeId). #### SubscriptionHealthStatus See API type definition [SubscriptionHealthStatus](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionHealthStatus). The health of the delivery infrastructure is independent of the `SubscriptionHealthStatus` and can be checked on the [status page](https://status.commercetools.com/). #### DeliveryFormat The format in which the payload is delivered. Defaults to [PlatformFormat](https://docs.commercetools.com/api/projects/subscriptions.md#platformformat). ##### PlatformFormat See API type definition [PlatformFormat](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3APlatformFormat). ##### CloudEventsFormat See API type definition [CloudEventsFormat](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ACloudEventsFormat). ## Get Subscription ### Get Subscription by ID See API endpoint definition [GET /\{projectKey}/subscriptions/\{id}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2F%7Bid%7D%3AGET). ### Get Subscription by Key See API endpoint definition [GET /\{projectKey}/subscriptions/key=\{key}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2Fkey%3D%7Bkey%7D%3AGET). ### Get Health Status of Subscription by ID See API endpoint definition [GET /\{projectKey}/subscriptions/\{id}/health](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2F%7Bid%7D%2Fhealth%3AGET). The HTTP status codes are mapped to the [SubscriptionHealthStatus](https://docs.commercetools.com/api/projects/subscriptions.md#subscriptionhealthstatus) as follows: - `200` - `Healthy` - `400` - `ConfigurationError`, `ConfigurationErrorDeliveryStopped`, and `ManuallySuspended` - `503` - `TemporaryError` ## Query Subscriptions See API endpoint definition [GET /\{projectKey}/subscriptions](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%3AGET). ## Check if Subscription exists ### Check if Subscription exists by ID See API endpoint definition [HEAD /\{projectKey}/subscriptions/\{id}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2F%7Bid%7D%3AHEAD). ### Check if Subscription exists by Key See API endpoint definition [HEAD /\{projectKey}/subscriptions/key=\{key}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2Fkey%3D%7Bkey%7D%3AHEAD). ### Check if Subscription exists by Query Predicate See API endpoint definition [HEAD /\{projectKey}/subscriptions](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%3AHEAD). ## Create Subscription See API endpoint definition [POST /\{projectKey}/subscriptions](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%3APOST). ## Update Subscription ### Update Subscription by ID See API endpoint definition [POST /\{projectKey}/subscriptions/\{id}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2F%7Bid%7D%3APOST). ### Update Subscription by Key See API endpoint definition [POST /\{projectKey}/subscriptions/key=\{key}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2Fkey%3D%7Bkey%7D%3APOST). ## Update actions #### Set Key See API type definition [SubscriptionSetKeyAction](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionSetKeyAction). #### Set Messages See API type definition [SubscriptionSetMessagesAction](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionSetMessagesAction). #### Set Changes See API type definition [SubscriptionSetChangesAction](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionSetChangesAction). #### Set Events See API type definition [SubscriptionSetEventsAction](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionSetEventsAction). #### Change Destination See API type definition [SubscriptionChangeDestinationAction](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ASubscriptionChangeDestinationAction). ## Delete Subscription ### Delete Subscription by ID See API endpoint definition [DELETE /\{projectKey}/subscriptions/\{id}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2F%7Bid%7D%3ADELETE). ### Delete Subscription by Key See API endpoint definition [DELETE /\{projectKey}/subscriptions/key=\{key}](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fsubscriptions%2Fkey%3D%7Bkey%7D%3ADELETE). ## Delivery The Delivery payload depends on the chosen [DeliveryFormat](https://docs.commercetools.com/api/projects/subscriptions.md#deliveryformat). ### Delivery payload for the PlatformFormat See API type definition [DeliveryPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ADeliveryPayload). #### MessageDeliveryPayload See API type definition [MessageDeliveryPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AMessageDeliveryPayload). 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](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Atype%3AMessage) 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](https://docs.commercetools.com/urn?urn=ctp%3Aapi%3Aendpoint%3A%2F%7BprojectKey%7D%2Fmessages%2F%7Bid%7D%3AGET) if the feature is enabled. ##### PayloadNotIncluded See API type definition [PayloadNotIncluded](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3APayloadNotIncluded). #### ResourceCreatedDeliveryPayload See API type definition [ResourceCreatedDeliveryPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AResourceCreatedDeliveryPayload). #### ResourceUpdatedDeliveryPayload See API type definition [ResourceUpdatedDeliveryPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AResourceUpdatedDeliveryPayload). #### ResourceDeletedDeliveryPayload See API type definition [ResourceDeletedDeliveryPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AResourceDeletedDeliveryPayload). #### EventDeliveryPayload See API type definition [EventDeliveryPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3AEventDeliveryPayload). ### Delivery payload for the CloudEventsFormat See API type definition [CloudEventsPayload](https://docs.commercetools.com/api/projects/subscriptions.md?urn=ctp%3Aapi%3Atype%3ACloudEventsPayload). ### Delivery guarantees #### At-least-once delivery If no positive acknowledgment is received that a notification has been accepted by the Destination, delivery will be retried. Our Retry Policy depends on the [SubscriptionHealthStatus](https://docs.commercetools.com/api/projects/subscriptions.md#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](https://docs.commercetools.com/api/projects/subscriptions.md#get-health-status-of-subscription-by-id) 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. ## Related pages - [Section overview page](https://docs.commercetools.com/api.md) - [Previous page: API Extensions](https://docs.commercetools.com/api/projects/api-extensions.md) - [Next page: Messages](https://docs.commercetools.com/api/projects/messages.md)