This feature is marked as beta and may be affected by changes. Use with caution for production.

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 the commercetools platform. Common use cases include sending an Order Confirmation Email, charging a Credit Card after the delivery has been made, or synchronizing customer accounts to a CRM system.

As a payload, they can either deliver the predefined Messages, or a generic change notification if a resource has been created, updated or deleted.

The first part of this document explains how to setup a subscription, while the second part details the payload and delivery guarantees.

Representations

Subscription

SubscriptionDraft

Either messages or changes need to be set.

Destination

A destination contains all info necessary for the commercetools platform to deliver a message onto your Message Queue. Message Queues can be differentiated by the type field.

Currently the Message Queues ↗ IronMQ , ↗ AWS SQS and ↗ AWS SNS are supported.

IronMQ Destination

↗ IronMQ can be used as a pull-queue, but it can also be used to push messages to IronWorkers or HTTP endpoints (webhooks) or fan-out messages to other IronMQ queues.

The webhook URI must contain a valid OAuth token. It roughly looks like this: https://...iron.io/.../queues/.../webhook?oauth=....

AWS SQS Destination

↗ AWS SQS is a pull-queue on AWS.

The queue needs to exist beforehand. It is recommended to create an accessKey and accessSecret pair specifically for each subscription that only has the sqs:SendMessage permission on this queue.

AWS SNS Destination

↗ AWS SNS can be used to push messages to AWS Lambda, HTTP endpoints (webhooks) or fan-out messages to SQS queues.

The topic needs to exist beforehand. It is recommended to create an accessKey and accessSecret pair specifically for each subscription that only has the sns:Publish permission on this topic.

MessageSubscription

types must contain valid message types for this resource, e.g. for resource type product the message type ProductPublished is valid. If no types of messages are given, the subscription is valid for all messages of this resource.

For supported resources and message types, please refer to the Messages Documentation. Messages will be delivered even if the Messages REST API is disabled.

The Message Subscription Payload is delivered.

ChangeSubscription

The following list of resourceTypeId are currently supported:

Different payloads for resource creation, update and deletion are delivered.

Get a Subscription

Get a Subscription by ID

Retrieves the representation of a subscription by its id.

Endpoint: /{projectKey}/subscriptions/{id}
Method: GET
OAuth2 Scopes: manage_subscriptions:{projectKey}
Response Representation: Subscription

Get a Subscription by Key

Retrieves the representation of a subscription by its key.

Endpoint: /{projectKey}/subscriptions/key={key}
Method: GET
OAuth2 Scopes: manage_subscriptions:{projectKey}
Response Representation: Subscription

Query Subscriptions

Endpoint: /{projectKey}/subscriptions
Method: GET
OAuth2 Scopes: manage_subscriptions:{projectKey}
Response Representation: PagedQueryResult with the results array of Subscription
Query Parameters:

Create a Subscription

Endpoint: /{projectKey}/subscriptions
Method: POST
OAuth2 Scopes: manage_subscriptions:{projectKey}
Request Representation: SubscriptionDraft
Response Representation: Subscription

The creation of a Subscription is eventually consistent, it may take up to a minute before it becomes fully active.

In order to test that the destination is correctly configured, a test message will be put into the queue. If the message could not be delivered, the subscription will not be created. The payload of the test message is a notification of type ResourceCreated for the resourceTypeId subscription.

Currently, a maximum of 25 subscriptions can be created per project.

Update Subscription

Updates of a Subscription are eventually consistent, it may take up to a minute before changes becomes fully active.

Update Subscription by ID

Endpoint: /{projectKey}/subscriptions/{id}
Method: POST
OAuth2 Scopes: manage_subscriptions:{projectKey}
Response Representation: Subscription
Fields:

Update Subscription by Key

Endpoint: /{projectKey}/subscriptions/key={key}
Method: POST
OAuth2 Scopes: manage_subscriptions:{projectKey}
Response Representation: Subscription
Fields:

Update Actions
Please find below the individual update actions provided on this endpoint.


Set Key

Set Messages

messages can only be unset if changes is set.

Set Changes

changes can only be unset if messages is set.

Delete Subscription

The deletion of a Subscription is eventually consistent, it may take up to a minute before it becomes fully deactived.

Delete Subscription by ID

Endpoint: /{projectKey}/subscriptions/{id}
Method: DELETE
OAuth2 Scopes: manage_subscriptions:{projectKey}
Query Parameters:

Delete Subscription by Key

Endpoint: /{projectKey}/subscriptions/key={key}
Method: DELETE
OAuth2 Scopes: manage_subscriptions:{projectKey}
Query Parameters:

Delivery

Delivery Payloads

All payloads share these common fields:

Message Subscription Payload

This payload will be sent for a MessageSubscription.

The payload will always contain the common fields id, version, sequenceNumber, resourceVersion, createdAt and lastModifiedAt for any message.

If the payload fits within the size limit of your message queue (the limit is often 256kb), all additional fields for the specific message are included as well (along with the type field). If the payload did not fit, it can be retrieved from the Messages endpoint if messages are enabled.

ResourceCreated Payload

This payload will be sent for a ChangeSubscription if a resource was created.

ResourceUpdated Payload

This payload will be sent for a ChangeSubscription if a resource was updated.

ResourceDeleted Payload

This payload will be sent for a ChangeSubscription if a resource was deleted.

Delivery Guarantees

At-least-once Delivery

If the commercetools platform did not get a positive acknowledgement that the message has been put into the message queue, it will retry to deliver the message for at least 48 hours. After that, the message may be dropped.

A side effect of the retry is that the same message may be put several times into the message queue. 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, or for other types the fields resource.id and version.

No guarantee on order

Messages are not guaranteed to be delivered in their natural order (e.g. 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 (e.g. 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 other notificationType, the fields resource.id, version and (in case of update) oldVersion can be used. Note that version is not sequential.

Deletion of Subscription in case of continuous failure

If all deliveries for a subscription fail for several days (e.g. if the Message Queue was deleted, or the access credentials saved in the destination became invalid), we reserve the right to delete the subscription. (In case of a production project, we will try to get in touch with you!)