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#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#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). - Change - This payload contains information about the [change to the resource](https://docs.commercetools.com/api/projects/subscriptions#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). 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](https://docs.commercetools.com/api/limits#subscriptions). Learn more about API Subscriptions in our self-paced Extensibility overview and Integration patterns modules. # Representations ### 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. #### AzureServiceBusDestination 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. #### GoogleCloudPubSubDestination 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 ### MessageSubscription #### MessageSubscriptionResourceTypeId ### ChangeSubscription #### ChangeSubscriptionResourceTypeId ### EventSubscription #### EventSubscriptionResourceTypeId ### SubscriptionHealthStatus 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#platformformat). #### CloudEventsFormat # Get Subscription ## Get Health Status of Subscription by ID The HTTP status codes are mapped to the [SubscriptionHealthStatus](https://docs.commercetools.com/api/projects/subscriptions#subscriptionhealthstatus) as follows: - `200` - `Healthy` - `400` - `ConfigurationError`, `ConfigurationErrorDeliveryStopped`, and `ManuallySuspended` - `503` - `TemporaryError` # Check if Subscription exists ## Check if Subscription exists by Query Predicate # Update Subscription ## Update Subscription by Key # Update actions ### Change Destination # Delete Subscription ## Delete Subscription by Key # Delivery The Delivery payload depends on the chosen [DeliveryFormat](https://docs.commercetools.com/api/projects/subscriptions#deliveryformat). ## Delivery payload for the PlatformFormat ### MessageDeliveryPayload 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/api/projects/ctp:api:type: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](https://docs.commercetools.com/api/projects/ctp:api:endpoint:/\{projectKey}/messages/\{id}:GET) if the feature is enabled. #### PayloadNotIncluded ### EventDeliveryPayload ## 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#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#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.