Subscriptions for notifications

Elevate, May 20-22-2025, Miami Beach, Florida

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

Changes subscribed to.

destination​
Destination​

Messaging service to which the notifications are sent.

messages​
Array of MessageSubscription​

Messages subscribed to.

format​

Format in which the payload is delivered.

status​

Status of the Subscription.

createdAt​
DateTime​

Date and time (UTC) the Subscription was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the Subscription.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA

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

Changes to be subscribed to.

destination​
Destination​

Messaging service to which the notifications are sent.

messages​
Array of MessageSubscription​

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​

Number of results requested.

Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​

Number of elements skipped.

Default: 0​Maximum: 10000​
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

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

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

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"​Enum: 01all​
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.

resourceTypeId​

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.

shopping-list

Messages related to Shopping Lists.

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.

resourceTypeId​

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.

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

Subscription

asapplication/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:
200

Subscription

asapplication/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
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.
sort
​​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

Default: 20​
offset
​
Int
​

Number of elements skipped.

Default: 0​
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​
var.<varName>
​
String
​

Predicate parameter values.

The parameter can be passed multiple times.
Response:
200

SubscriptionPagedQueryResponse

asapplication/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:
201

Subscription

asapplication/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:SubscriptionUpdateasapplication/json
Response:
200

Subscription

asapplication/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:SubscriptionUpdateasapplication/json
Response:
200

Subscription

asapplication/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: 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 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​
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:
200

Subscription

asapplication/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:
200

Subscription

asapplication/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​

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​

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

Reference to the resource that triggered the notification.

resourceUserProvidedIdentifiers​

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

notificationType​
String​
"ResourceUpdated"

Identifies the payload.

resource​
Reference​

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

notificationType​
String​
"ResourceDeleted"

Identifies the payload.

resource​
Reference​

Reference to the resource that triggered the notification.

resourceUserProvidedIdentifiers​

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 payload can be found inside the data field.

id​
String​

Unique identifier of the event.

specversion​
String​
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​
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.