Create subscription upgrade ============================== Add a subscription upgrade. Subscription can be upgraded to the new subscription or to the existing one. Upgrades can be of two types: full upgrade and partial upgrade. - Full upgrade: if the target quantity is greater or equal to the current quantity - Partial upgrade: if the target quantity is less than the current quantity Prerequisites ^^^^^^^^^^^^^ - Credentials as described in :doc:`/getting-started/authentication` - A subscription id - Verify that the subscription is eligible for an upgrade by using :doc:`/scenarios/subscriptiontransition-eligibility` C# ^^ To create a subscription upgrade, **SubscriptionId** is required. Next, get the instance of **CrayonApiClient** and then get the client token using the instance. Finally, call **Subscriptions.PostTransitionAsync()** method to create the upgrade for the subscription by passing the token, instance of **SubscriptionTransition** and **SubscriptionId**. .. code-block:: c# :emphasize-lines: 12 var transition = new SubscriptionTransition { Quantity = 1, ToCatalogItemId = "CFQ7TTC0LF8Q:0001:CFQ7TTC0K39X", TransitionType = "transition_only", BillingCycle = 1, Term = "P1M" }; var client = new CrayonApiClient("https://api.crayon.com/"); var token = client.Tokens.GetUserToken(clientId, clientSecret, userName, password).GetData().AccessToken; var result = client.Subscriptions.PostTransitionAsync(token, subscriptionId, transition); Request ^^^^^^^ Request Syntax: +---------+----------------------------------------------------------------------------+ | Method | Request URI | +=========+============================================================================+ | POST | *https://api.crayon.com/api/v1/subscriptions/{subscriptionId}/transition* | +---------+----------------------------------------------------------------------------+ Request Body: +-------------------+----------------------------------------------+-----------------------------------+ | Name | Type | Description | +===================+==============================================+===================================+ | transition | :doc:`/resources/SubscriptionTransition` | The transition to create | +-------------------+----------------------------------------------+-----------------------------------+ SubscriptionTransition Properties: +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | Name | Type | Description | +=========================+============================+============================================================================================================================+ | ToCatalogItemId | string | The license product subscribed to. | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | Quantity | int | Number of license for the subscription. | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | TransitionType | string | Transition type. | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | Term | string | An ISO 8601 representation of the term's duration. Supported values P1M (1 month), P1Y (1 year) and P3Y (3 years). | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | BillingCycle | BillingCycleEnum | Billing cycle. Monthly = 1, Annual = 2, None = 3, OneTime = 4, BiAnnually = 5, TwoYears = 7, ThreeYears = 8, Quarterly = 9 | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | FromCatalogItemId | string | The license product subscribed from. | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | FromSubscriptionId | string | The subscription id subscribed from. | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ | ToSubscriptionId | string | The subscription id subscribed to. | +-------------------------+----------------------------+----------------------------------------------------------------------------------------------------------------------------+ Request Headers: The following HTTP request headers are supported +------------------+----------------+-----------------------------------------------------------------+ | Header | Type | Description | +==================+================+=================================================================+ | Authorization | string | Required. The authorization token in the form Bearer . | +------------------+----------------+----------------------------------------------+------------------+ | 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/{subscriptionId}/transition" Accept: application/json Content-Type: application/json Authorization: Bearer < Token > Request Body: .. literalinclude:: /scenarios/_static/SubscriptionTransitionRequest.json :language: json Response ^^^^^^^^ If successful, this method returns the upgraded subscription as a :doc:`/resources/SubscriptionTransition` resource in the response body. Response Body: .. literalinclude:: /scenarios/_static/SubscriptionTransitionResponse.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. | +--------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+