Application Packaging Standard

Last updated 18-Mar-2019

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.

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 Dispatcher

APS Type and ID

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

GET /aps/2/resources?implementing(http://www.odin.com/oa/billing/sku/dispatcher/1.0)

The response will contain the APS ID of the SKU dispatcher as in the following example:

[{
   "aps": {
      "type": "http://www.odin.com/oa/billing/sku/dispatcher/1.0",
      "id": "c3fe59e3-96f5-4792-aa4c-41d24c7ff5dc",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T13:52:26Z"
   }
}]

SKU Structure

In the SKU dispatcher 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.

../../../../_images/sku-subscription-period.png

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.

../../../../_images/sku-resource.png

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 dispatcher exposes several operations on the vendor collection. For BSS and particularly for the SKU dispatcher, a vendor is the service provider or a reseller.

Typical request for an operation looks as follows:

{VERB} /aps/2/resources/{dispatcherId}/vendor/{vendorId}/{path-to-operation}

The request consists of the following elements:

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

At a moment, a request specifies only 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 reseller (vendor).
The required properties: id, price, and msrp.
The properties to be updated: price and msrp.
synchronize POST /vendor/{vendorId}/synchronize If the vendor whose APS ID is {vendorId} has changed the fees in the plans delegated to sub-resellers, those fees will be synchronized with all sub-resellers.

If both APS IDs, of the SKU dispatcher and the vendor, are identified, a request for one of the operations, for example, synchronize, will look as follows:

POST /aps/2/resources/c3fe59e3-96f5-4792-aa4c-41d24c7ff5dc/vendor/0ab950d1-abc9-4433-a87d-8ba009bf4bce/synchronize

On success, the response will be:

HTTP/1.1 204 No Content

Price Management

With the depicted SKU API, a third-party management system (kind of ERP) having a catalog of SKUs can manage the prices in BSS as follows:

  1. The provider assigns the SKUs from the catalog to the service plan fees.
  2. The management system verifies the list of fees with assigned SKUs by calling the rateList operation.
  3. If some SKU fees are changed in the management system, the latter synchronizes them with BSS by calling the updateRates operation.
  4. To sync the changes of the fees in the plans delegated by the provider or by a reseller to sub-resellers, the system calls the synchronize operation.