SALES: 1-800-867-1380

Create Subscription

Updated: January 3, 2013

Creates a new subscription. Once created, the subscription resource manifest is immutable. This operation is not idempotent. Repeating the create call after a subscription with same name (under same topic and namespace) has been created successfully, results in a “409 Conflict” error message.

If you create a subscription with a name that contains special or encoded characters (for example, "test?Name=value&", which gets encoded to "test%3FName%3Dvalue%26", a (401) Unauthorized exception is generated.

Subscription Name Restrictions:

  1. Can only contain only letters, numbers, periods (.), hyphens (-), and underscores (_).

  2. Multiple segments not allowed.

  3. Forward slash (/) not allowed as a prefix or suffix of the subscription name.

  4. Maximum number of characters is 50.


Method Request URI HTTP version

PUT{subscription ID}/services/ServiceBus/Namespaces/Topics/Subscriptions/{Subscription Name}


The following table describes required and optional request headers.


Request Header Description




Management Endpoint url



Note that the request also requires a client certificate. This certificate must match the certificate you uploaded for that particular subscription.

The following table describes the key elements of the request body:


Property Name Type Description


XML Datetime

Based on whether DeadLettering is turned on, if a message has been stored in the topic for more than the specified time, it is automatically moved to the DeadLetterQueue or deleted. This value is overwritten by a TTL specified on the message if the message TTL is smaller than the TTL set on the topic. This value is immutable after the topic has been created:

  • Range: 1 second – 14 days.

  • Default: 14 days.


XML Datetime

This setting determines the amount of time, in seconds, in which a message should be locked for processing by a receiver. After this period, the message is unlocked and available for consumption by the next receiver. Settable only at topic creation time:

  • Range: 0–5 min. 0 means that the message is not locked.

  • Default: 30s.



Settable only at topic creation time. If set to true, the topic is session aware and only SessionReceiver is supported. Session-aware topics are not supported through REST.

  • Default: False.



Settable only at subscription creation time.

  • Default: False.

This field determines how the Service Bus handles a message with an expired TTL. If it is enabled and a message expires, the Service Bus moves the message from the topic into the dead-letter subqueue for that topic. If disabled, the message is permanently deleted from the topic.


Determines how the Service Bus handles a message that causes an exception during a subscription filter evaluation. If the value is set to true, the message that caused the exception is moved to the subscription’s dead-letter queue. Otherwise, it is discarded. By default, this parameter is set to true, allowing the user to investigate the cause of the exception. It can occur from a malformed message, or incorrect assumptions being made in the filter about the form of the message. Settable only at topic creation time.

  • Default: true


Enables or disables service-side batching behavior when performing operations for the specific queue. When enabled, the Service Bus collects/batches multiple operations to the backend, to be more efficient in the connection. If you want lower operation latency, you can disable this feature.

Default: false


Unsigned Integer

The maximum number of times the Service Bus tries to deliver a message before the message is dead-lettered or discarded.

  • Default: 10


Unsigned Integer

Reports the number of messages in the subscription not dequeued yet, as reported by the monitoring system.

The response includes an HTTP status code and a set of response headers.

If you create a namespace with a name that contains special or encoded characters (for example, "test?Name=value&", which gets encoded to "test%3FName%3Dvalue%26", a (401) Unauthorized exception is generated.


Code Description


Subscription created successfully.


Invalid request body.


Authorization failure.


Quota exceeded; subscription not created.


The specified subscription already exists (or the specified path is already occupied).


Internal error.

For information about status codes, see Status and Error Codes.

The subscription description is returned because when the PUT request does not specify values for all attributes of the subscription, some description properties can be defaulted.

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
© 2014 Microsoft