:orphan:

Update subscription tags
========================

Update or create subscription tags.

Prerequisites
^^^^^^^^^^^^^

- Credentials as described in :doc:`/getting-started/authentication`
- A subscription identifier

C#
^^

To create or modify tags for a subscription, a valid id of an existing subscription needs to be set on subscription tags object.

Next, values for at least 1 tag value has to be set.

Keep in mind that this method is **idempotent**. In order to overwrite an existing tag without nullifying the others, they should be filled as well.

Sending subscription tags object with all tags set to null is equivalent to **deleting** a tag.

.. code-block:: c#
	:emphasize-lines: 9
	
	var subscriptionId = <subscription id>; 
	var client = new CrayonApiClient("https://api.crayon.com/");
	var token = client.Tokens.GetUserToken(clientId, clientSecret, userName, password).GetData().AccessToken;

	var subscriptionTags = client.Subscriptions.GetSubscriptionTagsAsync(token, subscriptionId).GetData();
	subscriptionTags.Department = "Department tag value";
	subscriptionTags.Owner = "Owner tag value";

	var result = client.Subscriptions.SetSubscriptionTagsAsync(token, subscription);


Request
^^^^^^^

Request Syntax:

+---------+-----------------------------------------------------------+
| Method  | Request URI                                               |
+=========+===========================================================+
| POST    | *https://api.crayon.com/api/v1/subscriptions/{id}/tags*   |
+---------+-----------------------------------------------------------+

Request Body:

+-------------------+-----------------------------------------+----------------------------------------+
| Name              | Type                                    | Description                            |
+===================+=========================================+========================================+
| subscription tags | :doc:`/resources/SubscriptionDetailed`  | The subscription tags to update        |
+-------------------+-----------------------------------------+----------------------------------------+

Request Headers:

The following HTTP request headers are supported

+------------------+----------------+-----------------------------------------------------------------+
| Header           | Type           | Description                                                     |
+==================+================+=================================================================+
| Authorization    | string         | Required. The authorization token in the form Bearer <token>.   |
+------------------+----------------+-----------------------------------------------------------------+
| Accept           | string         | Specifies the request and response type, "application/json".    |
+------------------+----------------+-----------------------------------------------------------------+
| Content-Type     | string         | Specifies the media type of the resource, "application/json".   |
+------------------+----------------+-----------------------------------------------------------------+

Request Example:

::

	POST $"https://api.crayon.com/api/v1/subscriptions/{id}/tags"
	Accept: application/json
	Content-Type: application/json 
	Authorization: Bearer < Token >	

.. literalinclude:: /resources/_static/SubscriptionTags.json
		:language: json


Response
^^^^^^^^

If successful, this method returns the updated subscription as a :doc:`/resources/SubscriptionDetailed` resource in the response body.

Response Body:

.. literalinclude:: /resources/_static/SubscriptionDetailed.json
		:language: json

Response success and error codes:

Each response comes with an HTTP status code that indicates success or failure and additional debugging information. Use a network trace tool to read this code, error type, and additional parameters.

+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Error Codes                    | Description                                                                                                                                                                                                                                                                               |
+================================+===========================================================================================================================================================================================================================================================================================+
| 200 Ok                         | The request has succeeded.                                                                                                                                                                                                                                                                |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 400 Bad Request                | The request could not be understood by the server due to malformed syntax, missing required properties, properties that couldn't be parsed according to their type (and length). It is a non-retryable error condition. The client should not repeat the request without modifications.   |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 401 Unauthorized               | The request requires user authentication. If the request already included Authorization credentials, then the 401 (Unauthorized) status code means that authorization has been refused for those credentials. It is a non-retryable error condition.                                      |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 404 Not Found                  | The server has not found anything matching the request.                                                                                                                                                                                                                                   |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+