Create subscription
===================

Create a subscription.

----------------------------------------

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

- Credentials as described in :doc:`/getting-started/authentication`
- A customer tenant identifier
- A product part number

C#
^^

To create subscription, first instantiate **SubscriptionDetailed** and set **CustomerTenant** property with the instantiated **CustomerTenantReference** with its property **Id** set to your tenant id.
Then set **Product** property with the instantiated **ProductReference** with its property **PartNumber** set with the part number value.

Next, get the instance of **CrayonApiClient** and then get the client token using the instance. This client token will be passed when creating the subscription.

Finally, call **Subscriptions.Create()** method to create subscription by passing the token and the instance of **SubscriptionDetailed**.

.. code-block:: c#
	:emphasize-lines: 21
	
	var subscription = new SubscriptionDetailed
	{
		Name = "My subscription",
		Quantity = 1,
		CustomerTenant = new CustomerTenantReference
		{
			Id = <tenant id>
		},
		Product = new ProductReference
		{
			PartNumber = "<part number>"
		}
	};

	var client = new CrayonApiClient("https://api.crayon.com/");
	var token = client.Tokens.GetUserToken(clientId, clientSecret, userName, password).GetData().AccessToken;
	var result = client.Subscriptions.Create(token, subscription);


Request
^^^^^^^

Request Syntax:

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

Request Body:

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

SubscriptionDetailed Properties:

+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Name                    | Type                                     | Required       | Description                                                                                                                              |
+=========================+==========================================+================+==========================================================================================================================================+
| Name                    | string                                   | Yes            | For Nce subscriptions, no names will be assigned.                                                                                        |
+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| CustomerTenant.Id       | int                                      | Yes            |                                                                                                                                          |
+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Product.PartNumber      | string                                   | Yes            |                                                                                                                                          |
+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| Quantity                | int                                      | Yes            |                                                                                                                                          |
+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| BillingCycle            | BillingCycleEnum                         | Only for Nce   | Billing cycle. Unknown = 0, Monthly = 1, Annual = 2, None = 3, OneTime = 4, BiAnnually = 5, TwoYears = 7, ThreeYears = 8, Quarterly = 9  |
+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+
| TermDuration            | string                                   | Only for Nce   | An ISO 8601 representation of the term's duration. Supported values are: "P1M" for (1 month), "P1Y" for (1 year) and "P3Y" for (3 years).|
+-------------------------+------------------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------+


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/"
	Accept: application/json
	Content-Type: application/json 
	Authorization: Bearer < Token >

Request Body:

.. literalinclude:: /scenarios/_static/SubscriptionRequest.json
		:language: json

Request Body for Nce subscriptions:

.. literalinclude:: /scenarios/_static/SubscriptionRequestNce.json
		:language: json

Response
^^^^^^^^
If successful, this method returns the created 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.                                                                                                                                                                                                                                   |
+--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+


Simplified endpoint to purchase a new commerce subscription
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The current endpoint should be able to handle all of the requirements for setting up a new Nce subscription, but there is also endpoint specialized for Nce.

:doc:`/scenarios/subscriptions-new-commerce-orders`