Subscription Create

Swagger documentation: POST API/Subscriptions/Create

The purpose of this endpoint is to create the subscription in the external system when an order is placed.

Note: Service Management API has been designed by having in mind that provisioning actions are based on the resources that need to be set each time to 3rd party system. Each time a subscription is created or updated, you should calculate the resources you need to provision by following the guidelines explained on the page How to Calculate the Resources to be Provisioned

Request & Response

The request contains the following objects and fields:

Name – The name of the subscription in the interworks.cloud platform.
ServiceType – The value of ProductTypeID as it was returned from the service manager by the Get Service Definition call. This may be a string of text, or any other service identifier.
ProductID – The ID of the product in the interworks.cloud platform.
ActionType – Determines the type of action requested for the subscription. For the Subscription Create endpoint, the ActionType is always Provision.
Quantity – the subscription quantity (amount of licenses).
Account – The details of the account which has purchased the subscription. This object contains the same fields as the Account Synchronize request.
AttributeList – Contains the properties of the subscription required by the Service Manager. For example, an attribute for a virtual machine may be Storage or RAM. Please refer to Get Services Definition – Product Type Attributes for more details.
- ID – The ID of the attribute
- Name – What the attribute is called (e.g., Storage)
- Value – The value of the attribute (e.g. 100)
- Code – If the attribute is a drop-down list, this is the code of the corresponding value in the list
- QuantityLinked – Whether the specific attribute affects the quantity of the subscription. For example, if the attribute is users, the value of the attribute (as specified in the field Value) must be multiplied by the quantity to determine the actual quantity to be provisioned. In this case, the value QuantityLinked must be true. If the attribute is storage, it does not affect the quantity of the subscription, and for such attributes QuantityLinked must be equal to false.
AllowMultipleSubscriptions – The value of this field indicates whether more than one subscription can be assigned to a customer. This is a property of the subscription product type. The value of this field depends on whether Maintain one active subscription is enabled in the product type properties.
IsFromOrder – Indicates whether the request was made due to an order execution in the BSS or a basket checkout from the Storefront (true), or by creating a subscription in the BSS (false).
BillingCycle – The billing cycle of the subscription (e.g., monthly, annual, etc.)
- Duration – The duration in the unit of time specified in DurationType
- DurationType – The unit of time (e.g. a bi-monthly subscription would have a DurationType of month and a Duration of 2).
- CustomEndDate – This is the date that has been specified by the user as the end date of the billing cycle.
RenewAutomatically – Indicates whether automatic renewal is activated or not for the subscription
IsTrial – Indicates whether the subscription is a trial
CheckOnly – This field should be true when the request is sent for validation purposes. Please refer to the Pre-check Mechanism page for more information.
InstallmentPlan – Contains the details for the installment plan, if applicable:
- Installments – The amount of installments
- Frequency – The frequency of installment payment in months

The response contains the following fields:

AccountExtraInfo – The contents of this field are stored and sent as ExtraDetails in every request. Any key-value pairs in this field can be used as variables in the notification template
Code – The error code. Only a value of 0 means that there no error occurred.
Message – A description of the error (if applicable)
Result – Contains the ID of the subscription in the external system. This ExternalID is then sent in every subsequent request
SendNotification – When set to true, an email with access instructions (described below) is sent to the customer.

When this Endpoint is Called

Subscription Create is called when:

An order is executed in the BSS
A subscription is created manually in the BSS
A product is purchased via the Storefront, during basket checkout.

Please refer to the following flow diagram(s) to see at which point(s) in the process the endpoint is called:

Implementation Checklist

To test this endpoint, you may:

Purchase a subscription via the Storefront
Execute an order containing a recurring order item in the BSS
Manually create a subscription in the BSS

Then, check if the subscription has been created successfully.

Email Notification

To send an email to the customer with information regarding their subscription, in the BSS go to Setup → Administration → System Options → Applications Setup, find the application, and select Edit Integration. Go to the Subscriptions section and enable Send email notification to customer.

The following is an example of an email notification with an activation link and a token:

Hello,

Your {#Products.DisplayString#} product has been purchased successfully!

Please visit the following Link and use the provided Token in order to activate & download your Product.
Token: [#MSESDTOKEN#]
Activation Link: [#MSESDLINK#]

Interworks Marketing Department
email: [email protected]

Products.DisplayString, MSESDTOKEN and MSESDLINK are all variables, and will change dynamically based on the account and/or the subscription.

Any key-value pairs in AccountExtraInfo in the response can be used as variables in the notification template. E.g., If the response contains “customer_location”: “us” in AccountExtraInfo, it can be used as [#customer_location#] in the notification template.

Subscription Update

Swagger documentation: POST API/Subscriptions/Update

The purpose of the subscription update endpoint is to update the record of the subscription in the external system whenever a change is made, such as the purchase of additional licenses.

Request & Response

The request and response of the subscription update endpoint are similar to those of the subscription create endpoint.

Please note that the Quantity field contains the current total amount of licenses, i.e., including those added or cancelled when the endpoint was triggered. To find the difference, please check the records in your system.

The Subscription Update also contains a few additional fields in its request:

ID – The ID returned by the external system when the service was provisioned. Specifies the ID of the subscription in the external system.
SubscriptionID – The ID of the subscription in the interworks.cloud platform.
ActionType – For the Subscription Update endpoint, the ActionType is Provision.
Add-ons – The selected add-ons for the subscription:
- ID – The ID of the add-on in the external system
- Name – The name of the add-on in the interworks.cloud platform.
- ProductID – The ID of the add-on as a product in your system.
- ActionType – The value of the ActionType field in a Subscription Update request is None.
- Quantity – The quantity of add-ons
- AttributeList – Contains the properties of the add-on in a similar way to the AttributeList of the subscription

The presence of values in the ID and SubscriptionID fields distinguish Subscription Update from Subscription Create.

Warning
Please note that the Subscription Update endpoint contains addons objects for informational purposes only. Since the provisioning of addons is handled by other endpoints, the ones are contained in Subscription Update are only used to indicate their availability in case a change in the subscription is required. For more information about addon management, please refer to the Addon Management Endpoints page.

When this Endpoint is Called

The Subscription Update endpoint is called when additional licenses are purchased for the subscription via the storefront, or when a quantity change is performed in the BSS.

Please refer to the following flow chart(s) to see at which point in the flow the endpoint is called:

Increase Quantity in Storefront

Implementation Checklist

To test this endpoint:

Purchase additional licenses or cancel licenses for a subscription via the Storefront
Increase or decrease the quantity of a subscription in the BSS

Then, check if the subscription has been updated according to your choices.

Subscription Status Management Endpoints

The following endpoints are all used for changing the status of the subscription in the external system. Select the endpoint to go to its swagger documentation:

Their purpose is to change the status of the subscription in the external system to what their names suggest.

Request & Response

All the endpoints in this section contain the same data in their requests as Subscription Create. The value of their ActionType fields corresponds to their purpose (activate/suspend/cancel).

The response contains the same fields as Subscription Create, minus the AccountExtraInfo field. Essentially, it contains the data required to confirm a successful status change, or, in case of an error, the error code and description.

When these Endpoints are Called & Implementation Checklist

Each endpoint is called when the corresponding action is performed in the BSS or the Storefront (if applicable). To test these endpoints, perform the corresponding actions and check the status of the subscription.

Additionally, you may see the following flow diagrams to see at which point Subscription Cancel is called:

Subscription Upgrade Downgrade

Swagger documentation: POST API/Subscriptions/UpgradeDowngrade

The purpose of the subscription upgrade downgrade endpoint is to update the record of the subscription in the external system whenever the subscription is upgraded or downgraded.

Request & Response

The request and response of the subscription upgrade downgrade endpoint are similar to those of the subscription update endpoint, however, the value of ActionType in this case is Upgrade or Downgrade, depending on the intended action. Additionally, the subscription receives a new ID and the OriginalSubscriptionID field stores the ID of the subscription before any upgrades were applied. This ID is retained in case any information from the original subscription is required.

When this Endpoint is Called

The Subscription Update endpoint is called when a subscription is upgraded via the storefront or in the BSS.

Implementation Checklist

To test this endpoint:

Upgrade a subscription via the Storefront
Downgrade a subscription via the Storefront
Upgrade a subscription in the BSS
Downgrade a subscription in the BSS

Then, check if the subscription has been updated according to your choices.

Subscription Upgrade to Paid

Swagger documentation: POST API/Subscriptions/UpgradeToPaid

The purpose of this endpoint is to update the record of a trial subscription in the external system whenever the subscription is upgraded to its paid version.

Request & Response

The request and response of the endpoint are similar to those of the subscription update endpoint, however, the value of ActionType in this case is UpgradeToPaid. Additionally, the subscription receives a new ID and the OriginalSubscriptionID field stores the ID of the subscription before any upgrades were applied.

When this Endpoint is Called

The Subscription Update endpoint is called when a trial subscription is upgraded to paid via the storefront or in the BSS.

Please refer to the following flow charts to see at which point in the flow the endpoint is called:

Implementation Checklist

To test this endpoint, upgrade an existing trial subscription to paid, then, check if the subscription record has been updated.