# Subscribe to Messages

In this tutorial, you will learn how to create a [Subscription](/api/projects/subscriptions.md) in your Project. While several [Destinations](/api/projects/subscriptions.md#destination) are supported, this tutorial covers three: Amazon Web Services EventBridge, Amazon Web Services Simple Queue Service (SQS), and Microsoft Azure Service Bus (ASB).

## Goal

Create a Subscription that sends a notification via email to your customer when an order is created.

## Prerequisites

1. Credentials for an API Client with the `Manage Subscriptions` scope. If you don't have an API Client yet, [create one](/merchant-center/developer-settings.md#create-an-api-client).

2. This tutorial covers three Destination types:

   - [AWS EventBridge](https://docs.aws.amazon.com/eventbridge/index.html): you need an [AWS account Identifier](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html#FindingYourAWSId) and the region in which you want to receive the messages. For help getting started, see [Getting started with Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html).
   - [AWS SQS](https://aws.amazon.com/sqs/): you need an AWS account and an SQS queue. For help getting started, see [Getting Started with Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-getting-started.html).
   - [Azure Service Bus (ASB)](https://azure.microsoft.com/en-us/products/service-bus/): you need an Azure account and a queue in Azure Service Bus. For help getting started, see [Create a queue using the Azure portal](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues?tabs=passwordless#create-a-queue-in-the-azure-portal).

## Create a Subscription

Before creating a Subscription, you need to gather some data from the destination service you are using.

### Access and queue

#### AWS EventBridge

You need your [AWS account Identifier](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html#FindingYourAWSId) and the region in which you want to receive the messages. When you create the Subscription, a new event source is automatically created in the specified AWS account and region. You can then associate the event source with an event bus and configure forwarding rules in the [AWS EventBridge console](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html).

#### AWS SQS

You need an access key ID and a secret access key. To learn how, see [create your own security credentials](https://docs.aws.amazon.com/general/latest/gr/managing-aws-access-keys.html).

You also need a queue in SQS. For instructions, see [create a queue and get the URL and the region of the queue](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-create-queue.html).

#### Azure

First, [create a queue in Azure Service Bus](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues?tabs=passwordless#create-a-queue-in-the-azure-portal). When you create the queue, ensure that the **Enable sessions** checkbox is unchecked, as this option is not supported by the API.

Next, get the connection string needed to create an ASB Subscription. For instructions, see [Get a Service Bus connection string](https://learn.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues?tabs=connection-string#create-a-queue-in-the-azure-portal).

### Messages

The `messages` field is an array of [MessageSubscriptions](/api/projects/subscriptions.md#messagesubscription) which require a `resourceTypeId`. For the full list of supported values, see [MessageSubscriptionResourceTypeId](/urn?urn=ctp%3Aapi%3Atype%3AMessageSubscriptionResourceTypeId).

The following code snippets show examples of passing `order` as `resourceTypeId` in different languages.

#### EventBridge Subscription

```json
{
  "destination": {
    "type": "EventBridge",
    "accountId": "<my-account-id>",
    "region": "<my-region>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

```

```java
// Create destination
EventBridgeDestination destination = EventBridgeDestination
  .builder()
  .accountId("<my-account-id>")
  .region("<my-region>")
  .build();

// Create SubscriptionDraft
final SubscriptionDraft subscriptionDraft = SubscriptionDraft
  .builder()
  .destination(destination)
  .messages(
    List.of(MessageSubscription.builder().resourceTypeId("order").build())
  )
  .build();

// Post SubscriptionDraft
final Subscription subscription = apiRoot
  .subscriptions()
  .post(subscriptionDraft)
  .executeBlocking()
  .getBody();

```

```ts
const createSubscription = apiRoot
  .subscriptions()
  .post({
    body: {
      destination: {
        type: "EventBridge",
        accountId: "<my-account-id>",
        region: "<my-region>"
      },
      messages: [{ resourceTypeId: "order" }]
    }
  })
  .execute();

```

```php
<?php
// Create destination
$destination = EventBridgeDestinationBuilder::of()
   ->withAccountId('<my-account-id>')
   ->withRegion('<my-region>')
   ->build();

// Create SubscriptionDraft
$subscriptionDraft = SubscriptionDraftBuilder::of()
   ->withDestination($destination)
   ->withMessages(
      MessageSubscriptionCollection::of()->add(
         MessageSubscriptionBuilder::of()->withResourceTypeId('order')->build(),
      ),
   )
   ->build();

// Post SubscriptionDraft
$subscription = $apiRoot->subscriptions()->post($subscriptionDraft)->execute();

```

```cs
// Create destination
var destination = new EventBridgeDestination()
    {
      Type = "EventBridge",
      AccountId = "<my-account-id>",
      Region = "<my-region>"
    };

// Create SubscriptionDraft
var subscriptionDraft = new SubscriptionDraft()
    {
      Destination = destination,
      Messages = new List<IMessageSubscription> {
        new MessageSubscription()
        {
          ResourceTypeId = "order"
        }
      }
    };

// Post SubscriptionDraft
var createSubscription = projectApiRoot
    .Subscriptions()
    .Post(subscriptionDraft)
    .ExecuteAsync();

```

```sh
#!/bin/sh
curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/{projectKey}/subscriptions -d @- << EOF
{
	"destination": {
		"type": "EventBridge",
		"accountId": "<my-account-id>",
		"region": "<my-region>"
	},
	"messages": [
		{
		    "resourceTypeId": "order"
		}
	]
}
EOF

```

If the creation was successful, you will get a response similar to the following:

```json
{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "accountId": "<my-account-id>",
    "region": "<my-region>",
    "source": "aws.partner/commercetools.com/<project-key>/eventbridge",
    "type": "EventBridge"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}
```

#### SQS Subscription

```json
{
  "destination": {
    "type": "SQS",
    "queueUrl": "<url-to-my-queue>",
    "authenticationMode": "IAM",
    "region": "<my-region>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

```

```java
// Create destination
SqsDestination destination = SqsDestination
  .builder()
  .queueUrl("<url-to-my-queue>")
  .accessKey("<my-access-key>")
  .accessSecret("<my-access-secret>")
  .region("<my-region>")
  .build();

// Create SubscriptionDraft
final SubscriptionDraft subscriptionDraft = SubscriptionDraft
  .builder()
  .destination(destination)
  .messages(
    List.of(MessageSubscription.builder().resourceTypeId("order").build())
  )
  .build();

// Post SubscriptionDraft
final Subscription subscription = apiRoot
  .subscriptions()
  .post(subscriptionDraft)
  .executeBlocking()
  .getBody();

```

```ts
const createSubscription = apiRoot
  .subscriptions()
  .post({
    body: {
      destination: {
        type: "SQS",
        queueUrl: "<url-to-my-queue>",
        accessKey: "<my-access-key>",
        accessSecret: "<my-access-secret>",
        region: "<my-region>"
      },
      messages: [{ resourceTypeId: "order" }]
    }
  })
  .execute();

```

```php
<?php
// Create destination
$destination = SqsDestinationBuilder::of()
   ->withQueueUrl('<url-to-my-queue>')
   ->withAccessKey('<my-access-key>')
   ->withAccessSecret('<my-access-secret>')
   ->withRegion('<my-region>')
   ->build();

// Create SubscriptionDraft
$subscriptionDraft = SubscriptionDraftBuilder::of()
   ->withDestination($destination)
   ->withMessages(
      MessageSubscriptionCollection::of()->add(
         MessageSubscriptionBuilder::of()
            ->withResourceTypeId('order')
            ->build(),
      ),
   )
   ->build();

// Post SubscriptionDraft
$subscription = $apiRoot
   ->subscriptions()
   ->post($subscriptionDraft)
   ->execute();

```

```cs
// Create destination
var destination = new SqsDestination()
    {
      Type = "SQS",
      QueueUrl = "<url-to-my-queue>",
      AccessKey = "<my-access-key>",
      AccessSecret = "<my-access-secret>",
      Region = "<my-region>"
    };

// Create SubscriptionDraft
var subscriptionDraft = new SubscriptionDraft()
    {
      Destination = destination,
      Messages = new List<IMessageSubscription> {
        new MessageSubscription()
        {
          ResourceTypeId = "order"
        }
      }
    };

// Post SubscriptionDraft
var createSubscription = projectApiRoot
    .Subscriptions()
    .Post(subscriptionDraft)
    .ExecuteAsync();

```

```sh
#!/bin/sh
curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/{projectKey}/subscriptions -d @- << EOF
{
	"destination": {
		"type": "SQS",
		"queueUrl": "<url-to-my-queue>",
		"accessKey": "<my-access-key>",
		"accessSecret": "<my-access-secret>",
		"region": "<my-region>"
	},
	"messages": [
		{
		    "resourceTypeId": "order"
		}
	]
}
EOF

```

If the creation was successful, you will get a response similar to the following:

```json
{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "accessKey": "<my-access-key>",
    "accessSecret": "<my-access-secret>",
    "queueUrl": "<my-queue-url>",
    "region": "<my-region>",
    "type": "SQS",
    "authenticationMode": "Credentials"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}
```

#### ASB Subscription

```json
{
  "destination": {
    "type": "AzureServiceBus",
    "connectionString": "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>"
  },
  "messages": [
    {
      "resourceTypeId": "order"
    }
  ]
}

```

```java
// Create destination
AzureServiceBusDestination destination = AzureServiceBusDestination
  .builder()
  .connectionString(
    "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>"
  )
  .build();

// Create SubscriptionDraft
final SubscriptionDraft subscriptionDraft = SubscriptionDraft
  .builder()
  .destination(destination)
  .messages(
    List.of(MessageSubscription.builder().resourceTypeId("order").build())
  )
  .build();

// Post SubscriptionDraft
final Subscription subscription = apiRoot
  .subscriptions()
  .post(subscriptionDraft)
  .executeBlocking()
  .getBody();

```

```ts
const createSubscription = apiRoot
  .subscriptions()
  .post({
    body: {
      destination: {
        type: "AzureServiceBus",
        connectionString:
          "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>"
      },
      messages: [{ resourceTypeId: "order" }]
    }
  })
  .execute();

```

```php
<?php
// Create destination
$destination = AzureServiceBusDestinationBuilder::of()
   ->withConnectionString(
      'Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>',
   )
   ->build();

// Create SubscriptionDraft
$subscriptionDraft = SubscriptionDraftBuilder::of()
   ->withDestination($destination)
   ->withMessages(
      MessageSubscriptionCollection::of()->add(
         MessageSubscriptionBuilder::of()->withResourceTypeId('order')->build(),
      ),
   )
   ->build();

// Post SubscriptionDraft
$subscription = $apiRoot->subscriptions()->post($subscriptionDraft)->execute();

```

```cs
// Create destination
var destination = new AzureServiceBusDestination()
    {
      Type = "AzureServiceBus",
      ConnectionString =
        "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>"
    };

// Create SubscriptionDraft
var subscriptionDraft = new SubscriptionDraft()
    {
      Destination = destination,
      Messages = new List<IMessageSubscription> {
        new MessageSubscription()
        {
          ResourceTypeId = "order"
        }
      }
    };

// Post SubscriptionDraft
var createSubscription = projectApiRoot
    .Subscriptions()
    .Post(subscriptionDraft)
    .ExecuteAsync();

```

```sh
#!/bin/sh
curl -sH "Authorization: Bearer ACCESS_TOKEN" https://api.{region}.commercetools.com/{projectKey}/subscriptions -d @- << EOF
{
	"destination": {
		"type": "AzureServiceBus",
		"connectionString": "Endpoint=sb://<namespace>.servicebus.windows.net/;SharedAccessKeyName=<key-name>;SharedAccessKey=<key>;EntityPath=<queue-name>"
	},
	"messages": [
		{
		    "resourceTypeId": "order"
		}
	]
}
EOF

```

If the creation was successful, you will get a response similar to the following:

```json
{
  "changes": [],
  "createdAt": "<timestamp>",
  "destination": {
    "connectionString": "<my-connectionString>",
    "type": "AzureServiceBus"
  },
  "id": "<subscription-id>",
  "lastModifiedAt": "<timestamp>",
  "messages": [
    {
      "resourceTypeId": "order",
      "types": []
    }
  ],
  "version": 1
}
```

## Receive a message using PHP and SQS

To receive a message from the queue and use its body to send a notification, you need to poll it from the queue. For the purpose of this tutorial, the following example prints the message body in the browser using PHP. You are free to use any language you prefer.

Create a PHP file with the following snippet. For the client, we use the factory method. For more details, see the [SQS documentation](https://docs.aws.amazon.com/aws-sdk-php/v2/guide/service-sqs.html).

```php

$client = SqsClient::factory(array(
    'profile' => '<my-profile>',
    'region'  => '<my-region>'
));

$result = $client->receiveMessage(array(
    'QueueUrl' => <my-queue-url>,
));

foreach ($result->getPath('Messages/*/Body') as $messageBody) {
    // Do something with the message
    echo $messageBody;
}

```

When you run this code, and if you have a message in your queue, you will see its body in the browser.

## Further learning

From here, you can discover other Subscription options, such as updating and deleting [Subscriptions](/api/projects/subscriptions.md), as well as other [predefined Messages](/api/projects/messages.md).

Learn more about how to utilize Subscriptions in our self-paced Integration patterns module.

## Related pages

- [Area overview page with navigation](/tutorials.md)
- [Previous page: Implement an API Extension](/tutorials/extensions.md)
- [Next page: Subscribe to Messages on AWS EventBridge](/tutorials/subscriptions-eventbridge.md)