Price Management¶

The SKU based interface considered here is designed for the third-party management systems that keep a catalog of products with assigned SKUs including a list of cloud-based products sold through the platform BSS.

In this document:

SKUs and Vendors
SKU Manager
Operations
Price Management

SKUs and Vendors ¶

The API considered here implies the following BSS configuration:

SKUs are assigned to the fees managed through the API. The SKUs section explains the configuration steps in the BSS provider control panel.
The provider has sales channels based on resellers whom the provider delegates service plans and service templates as explained in the Customization for Sales Channels document.

In terms of this BSS API, the provider and every reseller is a service vendor.

Note

Do not confuse the vendor term used in BSS with ISV or Application Vendor.

SKU Manager ¶

APS Type and ID¶

The built-in SKU manager is a singleton resource (service) based on the SKUManagement APS type. Once SKU integration is enabled, you can find the SKU manager APS ID by the following request:

GET /aps/2/services/sku-manager

The response will contain the aps section of the SKU manager as in the following example:

{
   "aps": {
      "schema": "/aps/2/types/185",
      "package": {
         "id": "7c48eafd-f659-48d6-8ca3-78945991f15a",
         "href": "/aps/2/packages/7c48eafd-f659-48d6-8ca3-78945991f15a"
      },
      "modified": "2019-01-15T08:54:24Z",
      "id": "58ef740e-e8ee-4d3b-a9be-462c0d12c4b3",
      "type": "http://www.odin.com/oa/billing/sku/dispatcher/1.0",
      "status": "aps:ready",
      "revision": 2
   }
}

Note

Before running custom operations exposed by the SKU manager, add the GET and POST HTTP methods to the list of allowed operations for the corresponding user as explained in the Set Up the User’s Credentials section. In that configuration, the APS ID equals the type property in the above response without the final slash and the version.

SKU Structure¶

In the SKU manager APS type, the main structure is SKU sent in the request body or in the response body depending on the operation. In BSS, a SKU configuration is flexible in terms of its assignment to a unique fee or to a scope of fees.

When configuring a cloud service, the price can be configured as a set of fees at the resource level (recommended) or at the service plan level (for every subscription period). The combination of fees at both levels is also often used. Typically, when an application service price depends on the number of seats, the price policy looks as follows:

At the service plan level, there is a concept of “included quantity”. The included quantity is the default quantity that the service comes with. For example, the application service is allowed for up to 5 users by default (minimum and included) and its price is configured at the service plan level.
The price for additional seats are configured at the resource level.

In the following example, SKUs are assigned to non-zero setup and recurring fees for the 1-month subscription period, although it is possible to have a SKU assigned to a group of fees.

The JSON representation of the above two SKUs (setup and recurring fees for the 1-month subscription) looks as the following two structures:

[
   {
      "id": 1,
      "name": "user-management-1month-setup",
      "description": {
         "en_US": "Demo cloud VPS and User Management service - setup fee for 1 month period."
      },
      "price": {
         "value": "2.0",
         "code": "USD"
      },
      "msrp": {
         "code": "USD"
      },
      "feeTypes": [
         "SETUP"
      ],
      "plans": [
         "4"
      ]
   },

   {
      "id": 2,
      "name": "user-management-1month-recurring",
      "description": {
         "en_US": "Demo cloud VPS and User Management service - 1 month recurring fee."
      },
      "price": {
         "value": "4.25",
         "code": "USD"
      },
      "msrp": {
         "code": "USD"
      },
      "feeTypes": [
         "RECURRING"
      ],
      "plans": [
         "4"
      ]
   },
   ...
]

A SKU structure shows the recommended price MSRP, the assigned price, the fee type, and the BSS internal ID of the service plan.

Similarly, in the following example presenting a resource rate, the provider assigns a separate SKU to the resource recurring fee.

Note

It is also possible to differentiate resource fees and the assigned SKUs by subscription periods.

The JSON representation of the above SKU looks as the following structure:

[
   {
      "id": 4,
      "name": "user-management-resource-MainstreamProfile-recurring",
      "description": {
         "en_US": "Demo cloud VPS and User Management service -
               recurring fee for every additional Mainstream profile of a VPS."
      },
      "price": {
         "value": "1.0",
         "code": "USD"
      },
      "msrp": {
         "code": "USD"
      },
      "feeTypes": [
         "RECURRING"
      ],
      "resources": [
         "1000106"
      ]
      "plans": [
         "4"
      ],
   },
   ...
]

In addition to the earlier mentioned parameters, the SKU also shows the BSS internal ID of the resource used to create the respective resource rate in the specified service plan.

Operations ¶

The SKU manager exposes several operations on the vendor collection.

Typical request for an operation looks as follows:

{VERB} /aps/2/services/sku-manager/vendor/{vendorId}/{path-to-operation}

The request consists of the following elements:

{VERB} is one of HTTP requests, either POST, GET or PUT.
{vendorId} is the vendor APS ID.
{path-to-operation} is the relative path for the operation in the URI.

At a time, a request specifies one vendor as an APS resource based on the standard Account APS type.

OPERATION	URI Path	Description
`rateList`	GET /vendor/{vendorId}/rates	Returns an array of SKUs in the response body.
`rateList`	GET /vendor/{vendorId}/rates?appId={AppId}	Returns an array of SKUs bound to the specified APS application. {AppId} is the APS ID assigned to the APS application in its `APP-META.xml` file.
`updateRates`	PUT /vendor/{vendorId}/rates	Accepts an array of SKUs in the request body to update them for the specified vendor. The required properties: `id`, `price`, and `msrp`. The properties to be updated: `price` and `msrp`.