Get Services Definition (Pay Per Use Services)

Table of Contents

1 Defining your Product Types
2 Generic Fields
3 Products Collection

This page describes how you can define your pay per use offerings and services by implementing the Get Services Definition endpoint. In the interworks.cloud platform, services are defined as products which belong to a product type.

The product type is the most fundamental entity for defining a service in the platform. It establishes the properties and attributes of the service which affect the provisioning, billing, ordering, marketing aspects of services on the platform.
Products are used by product managers to define the editions of a service by setting specific values for each attribute. In this way, the products are “instances” of the product types, meaning that you can have many products of the same type, while each product has only one product type.

To get familiar with the interworks.cloud product model, please refer to the Defining your Product Catalog page before implementing this endpoint.

The minimum requirement to implement this endpoint is to use it to define your product types. Such an approach is useful for fewer, less complex services. This way, the products can be created manually. Otherwise, for a large amount of products that are changed or updated on a regular basis, it is strongly recommended to use this endpoint to create the products.

Defining your Product Types

This endpoint should return one or more product types. The amount of product types to implement depends on the services you are offering. It is a good practice to create a product type per product family (e.g. for Microsoft services we have different product types for the Office 365 plans and the Dynamics plans).

For PPU services, the Get Services Definition endpoint contains the same fields as the one for Recurring Services. The differences are explained in detail below:

Generic Fields

The following screenshot displays the available options for creating a product type in the BSS portal. These are the generic fields you should also define for your product type.

"ID": "azureservice",
"Name": "Azure Service",
"Description": "The definition of an example service",
"AutoExecuteAddonCancelRequest": false,
"AutoExecuteSubscriptionCancelRequest": false,
"AutoExecuteSubscriptionDowngradeRequest": false,
"QuantityLimit": 1,
"QuantityLimitLocked": true,
"AllowMultipleSubscriptions": true,
"Scope": "Both",
"PortalURL": "https://portal.vendor.com",

Please note that for PPU services, QuantityLimit should be set to 1, and QuantityLimitLocked should be set to true.

For a more detailed look at the fields above, as well as Product Type Attributes and Product Type Rules please see the page: Get Services Definition (Recurring Services).

Products Collection

ProductsCollection contains all your products, with their attributes as defined in the Product Type.

{
    "ID": "Product_1_basic",
    "Code": "Product_1",
    "Name": "Product_1_Name",
    "Description": "This is the description of Product_1.",
    "AttributeList": [
        {
          "ID": "edition",
          "Values": "Basic"
        }
     ],
    "ChargeType": "RecurringPayPerUse",
    "UnitType": "Monthly",
    "UnitBillingCycles": [
        "Monthly",
    ],
    "UpdateOptions": [
        "Name",
        "UnitBillingCycles",
        "Prices"
    ],
    "IsActivated": true,
    "BillingOptionRecurringChargePayPerUse": {
        "BillingType": "RecurringChargePayPerUse",
        "BillingModel": 0,
        "NoOfDecimals": 2,
        "ChargeRule": "FULL",
        "UpFrontBilling": true
    }
}

ChargeType – The value of this field is always RecurringPayPerUse for PPU services.
UnitType – An alphanumeric value describing the type of a single unit of the product, e.g. Licenses, Users, Gigabytes, Virtual Machines, Domains. In other words, specifies what the quantity of the product is measured in. Unit types can be managed in the Setup mode of the BSS.
UnitBillingCycles – It is recommended for this field to only contain Monthly.
UpdateOptions – This field specifies the properties which are updated every time the endpoint is called. Only applies to the following fields:
- Name
- UnitBillingCycles
- TrialOffer
- TrialAttributes
- Prices
- RelatedProducts
IsActivated – Whether the product is activated
BillingOptionRecurringChargePayPerUse – contains the options seen in the figure below:

BillingOptionRecurringChargePayPerUse consists of the following fields:

BillingType – Must be RecurringChargePayPerUse for PPU servicesChargeRule – Whether to charge for the partial or full billing period
Billing Model – The value of this field (0, 1 or 2) corresponds to one of the models listed below:
- Usage – This model is for a PPU product that allows customers to pay as they consume and requires no commitment.
- UsageMininimumCommitment – Customers are charged a fixed minimum commitment amount at the end of month, which increases based on the resources consumed.
- Hybrid – Customers are charged a pre-fixed amount during purchase. This amount is charged for every subscription renewal. In addition to this, customers are also charged in the end of month if the consumption is higher than the fixed paid amount.
BillingDate – Whether to specify a specific billing date, use the customer’s option or exclude the product from prorata.
- CustomerOption – The billing date is specified by the customer.
- ExcludeFromProrata – The product is excluded from prorata.
- SpecificBillingDate – The billing date, which if set, only applies when this option is selected. The value can be any integer ranging from 1 to 31. For PPU services it is recommended to set the value of this field to 1, since PPU services are billed every calendar month.
Term – A numerical value for the term (in months) for which price protection applies.
NoOfDecimals – An integer specifying the number of decimal digits in the price ranging from 0 to 10
LockOptions – Indicates which of the above options users are prevented from editing.

It is recommended not to specify prices, since they are dynamic and based on consumption. Further information regarding the PPU usages and billing items endpoints can be found here: Pay Per Use Subscription Management

Please see the following pages for detailed information on additional properties of the Get Services Definition Endpoint: