List Products¶

The generic BSS APS REST interface allows external systems to get a JSON representation of service plans and other related objects.

In this document:

APS Types
Service Plans
Notification Template
Plan Categories
Resources
Service Terms
Tax Categories

APS Types ¶

A service plan is a complex object presenting a product for sale and related to many other business support objects.

In the APS model, a service plan is an APS resource created from the ServicePlan APS type which has a relationship with other APS types.

In the diagram, the blue colored boxes (PAAccount and PAServiceTemplate) represent the APS types of the OSS platform that the service plan APS type is related to. The other boxes represent APS types exposed by BSS.

APS TYPE	APS ID	Description
Service Plans	`http://www.odin.com/billing/ServicePlan/1.0`	A cloud service product; a commercial offering.
Notification Template	`http://www.odin.com/billing/NotificationTemplate/1.0`	A mail notification template in BSS used to send an event by email.
Resources	`http://www.odin.com/billing/Resource/1.0`	A resource in BSS.
Plan Categories	`http://www.odin.com/billing/ServicePlanCategory/1.0`	A service plan category (or simply plan category) used to group service plans.
Service Terms	`http://www.odin.com/billing/ServiceTerms/1.0`	Service terms that determine the service deactivation process.
Tax Categories	`http://www.odin.com/billing/TaxCategory/1.0`	A tax category is assigned to a group of products to include them into a tax calculation algorithm.

Service Plans ¶

List of Service Plans¶

The ServicePlan APS type allows an external system to get a list of all service plans, or a list of service plans defined by specific criteria. Usually, this is one of pre-sale operations running by the provider or a reseller.

All Service Plans¶

The following request must return a list of all service plans available for the requester:

GET /aps/2/collections/service-plans

The response will look like this (details are omitted):

HTTP/1.1 200 OK

[
   {
      "aps": {/* ... */},
      "billingTerms": {/* ... */},
      "resourceRates": [],
      "longDescription": {/* ... */},
      "name": {
         "en_US": "User Management Demo"
      },
      "publication": {/* ... */},
      "shortDescription": {/* ... */},
      "subscriptionPeriods": [],
   },
   {
      "aps": {/* ... */},
      "billingTerms": {/* ... */},
      "resourceRates": [],
      "longDescription": {/* ... */},
      "name": {
         "en_US": "Resource Consumption"
      },
      "publication": {/* ... */},
      "shortDescription": {/* ... */},
      "subscriptionPeriods": [],
   },
   /* ... */
]

List of selected Service Plans¶

It is possible to add RQL filters to narrow the list of service plans down, such as the following:

Get all published service plans (products ready for sale):

GET /aps/2/collections/service-plans?eq(publication.published,true)

Omit service plan details, for example, show only the names that are in English:
```
GET /aps/2/collections/service-plans?select(name.en_US)
```
Note

The response will still contain the aps:{…} section, even though it was not requested.

Similarly to the previous request, show only the names and subscription periods:

GET /aps/2/collections/service-plans?select(name.en_US,subscriptionPeriods)

Similarly, show the names and resource rates:

GET /aps/2/collections/service-plans?select(name.en_US,resourceRates)

Service Plan Details¶

If the management system knows the APS ID of a service plan, it can request its full JSON representation.

GET /aps/2/resources/314dac37-d3bd-4978-b05e-ba4658514485

The response will look like this (details are omitted):

HTTP/1.1 200 OK

{
   "aps": {/* ... */},
   "name": {/* ... */},
   "shortDescription": {/* ... */},
   "longDescription": {/* ... */},
   "subscriptionPeriods": [
      {
         "autoRenewalPeriod": {/* ... */},
         "numberOfBillingPeriods": 1,
         "trial": false,
         "defaultPeriod": false,
         "fees": {
            "setup": {
               "price": {/* ... */},
               "description": {/* ... */},
               "showZeroPrice": false
            },
            "recurring": {
               "price": {/* ... */},
               "description": {/* ... */},
               "showZeroPrice": false
            },
            "renewal": {/* ... */},
            "deposit": {/* ... */}
         },
         "refund": {/* ... */},
         "active": true
      }
   ],
   "resourceRates": [
      {
         "resourceId": "9baec2f7-2995-4527-8299-806687b148f1",
         "showInStore": true,
         "measurable": false,
         "showInCustomerPanel": true,
         "sortNumber": 999,
         "fees": {
            "setup": {/* ... */},
            "recurring": {/* ... */},
            "overuse": {/* ... */}
         },
         "publication": {/* ... */},
         "units": {/* ... */}
      },
      /* ... */
   ],
   "billingTerms": {/* ... */},
   "publication": {/* ... */},
   "category": {/* ... */},
   "serviceTemplate": {/* ... */},
   "serviceTerms": {/* ... */},
   "vendor": {/* ... */},
   "resources": {/* ... */}
}

Pricing¶

The previous section demonstrates a service plan as one of the most complicated APS resources, in which one of the most important sections is fees. This section exists inside a subscription period (to specify the fees for the period) and inside a resource rate (to specify the fees for the resource limit or resource usage). For resources, the fees are assigned per resource unit and typically include setup (a one-time fee), recurring (a periodical fee), and overuse fees. To encourage customers to buy more resources, a sales vendor can reduce the fees per resource unit if a customer buys a resource amount above a certain level. In this case, the fees are broken into tiers as in the following sample snippet:

"fees": {
   /* ... some properties are omitted */
   "setupTiers": null,
   "recurringTiers": [
      {
         "price": {
            "value": "1.5",
            "code": "USD"
         },
         "lowerLimit": "0.0"
      },
      {
         "price": {
            "value": "1.2",
            "code": "USD"
         },
         "lowerLimit": "10.0"
      },
      {
         "price": {
            "value": "10.0",
            "code": "USD"
         },
         "lowerLimit": "20.0"
      }
   ],
   "overuseTiers": null
}

The Provider Guide contains more details about the prices and refunds.

Resource Dependencies¶

The BSSResource APS type declares the dependsOn array containing a list of resources that a particular resource depends on. A resource (for example, called ResourceA) can depend on another resource (called ResourceB) in one of the following ways that is indicated by the kind property:

SUBSCRIPTION_WIDE_CONFLICTS: ResourceA cannot be with ResourceB in the same subscription.
ACCOUNT_WIDE_CONFLICTS: an account is allowed to have either ResourceA or ResourceB, but not both.
REQUIRES: ResourceA requires ResourceB to be added to the same subscription.
PROVIDED_BY: ResourceA will be automatically added to the subscription if ResourceB is added to this subscription.

Note

When purchasing a service plan through the REST API, the external system must select resources correctly in accordance with the resource dependency, except for the PROVIDED_BY dependency, which is resolved by the platform automatically.

This is a sample request for the dependsOn lists in all resources of the specified service plan:

GET /aps/2/collections/service-plans?eq(planId,4),select(name.en_US,resources.name.en_US,resources.dependsOn)

The response will look like this:

HTTP/1.1 200 OK

[
  {
    "aps": {
      "modified": "2019-06-07T11:29:44Z",
      "id": "f949357e-76b5-404a-9722-8b14710d4730",
      "type": "http://www.odin.com/billing/ServicePlan/1.1",
      "status": "aps:ready",
      "revision": 6
    },
    "name": {
      "en_US": "Testing Resource Dependencies"
    },
    "resources": [
      {
        "aps": {
          "modified": "2019-06-07T13:38:45Z",
          "id": "14d9d218-114e-4640-836c-69bc58e9b3a9",
          "type": "http://www.odin.com/billing/Resource/1.3",
          "status": "aps:ready",
          "revision": 7
        },
        "name": {
          "en_US": "MSS - Gold Configuration (conflicts with other configurations)"
        },
        "dependsOn": [
          {
            "resource": "35aab9dd-ea5e-4722-9dda-83d7cd8b8fa3",
            "kind": "SUBSCRIPTION_WIDE_CONFLICTS"
          },
          {
            "resource": "301c27cf-5373-47da-9a5c-b482d8ab15b8",
            "kind": "SUBSCRIPTION_WIDE_CONFLICTS"
          }
        ]
      },
      {
        "aps": {
          "modified": "2019-06-07T13:38:58Z",
          "id": "301c27cf-5373-47da-9a5c-b482d8ab15b8",
          "type": "http://www.odin.com/billing/Resource/1.3",
          "status": "aps:ready",
          "revision": 7
        },
        "name": {
          "en_US": "MSS - Platinum Configuration (conflicts with other configurations)"
        },
        "dependsOn": [
          {
            "resource": "14d9d218-114e-4640-836c-69bc58e9b3a9",
            "kind": "SUBSCRIPTION_WIDE_CONFLICTS"
          },
          {
            "resource": "35aab9dd-ea5e-4722-9dda-83d7cd8b8fa3",
            "kind": "SUBSCRIPTION_WIDE_CONFLICTS"
          }
        ]
      },
      {
        "aps": {
          "modified": "2019-06-07T13:38:33Z",
          "id": "35aab9dd-ea5e-4722-9dda-83d7cd8b8fa3",
          "type": "http://www.odin.com/billing/Resource/1.3",
          "status": "aps:ready",
          "revision": 10
        },
        "name": {
          "en_US": "MSS - Silver Configuration (conflicts with other configurations)"
        },
        "dependsOn": [
          {
            "resource": "14d9d218-114e-4640-836c-69bc58e9b3a9",
            "kind": "SUBSCRIPTION_WIDE_CONFLICTS"
          },
          {
            "resource": "301c27cf-5373-47da-9a5c-b482d8ab15b8",
            "kind": "SUBSCRIPTION_WIDE_CONFLICTS"
          }
        ]
      },
      {
        "aps": {
          "modified": "2019-06-06T14:43:20Z",
          "id": "3f462e79-4717-4233-8cb9-fa44b5d8e4fd",
          "type": "http://www.odin.com/billing/Resource/1.3",
          "status": "aps:ready",
          "revision": 2
        },
        "name": {
          "en_US": "MSS - VPS"
        }
      },
      {
        "aps": {
          "modified": "2019-06-07T11:32:02Z",
          "id": "372c60e0-4692-4f49-89f1-c9e5f96b8bb2",
          "type": "http://www.odin.com/billing/Resource/1.3",
          "status": "aps:ready",
          "revision": 4
        },
        "name": {
          "en_US": "MSS - Storage (requires Platinum conf.)"
        },
        "dependsOn": [
          {
            "resource": "301c27cf-5373-47da-9a5c-b482d8ab15b8",
            "kind": "REQUIRES",
            "multiplier": 1
          }
        ]
      },
      {
        "aps": {
          "modified": "2019-06-07T11:32:29Z",
          "id": "fda0678c-280a-4be4-9666-9e81a7ab57ba",
          "type": "http://www.odin.com/billing/Resource/1.3",
          "status": "aps:ready",
          "revision": 3
        },
        "name": {
          "en_US": "MSS - Storage Protection (requires Storage)"
        },
        "dependsOn": [
          {
            "resource": "372c60e0-4692-4f49-89f1-c9e5f96b8bb2",
            "kind": "REQUIRES",
            "multiplier": 1
          }
        ]
      }
    ]
  }
]

According the response, the “Testing Resource Dependencies” service plan contains the following resource dependencies:

Only one VPS configuration can be used, either “…Gold…”, “…Platinum…”, or “…Silver…”, because they conflict with each other.
The “…Storage…” resource requires the “…Platinum…” configuration.
The “…Storage Protection…” resource requires the “…Storage…” resource.

When processing an order on a service plan the platform verifies that the order complies with resource dependencies and rejects the order if the REQUIRES dependency type is broken as explained in Resource Dependency Validation.

Notification Template ¶

BSS contains a lot of notification templates used to send notifications by email on various occasions.

List of Notification Templates¶

To get a list of all notification templates in BSS, the management system must issue the following request:

GET /aps/2/collections/notification-templates

A response will look similar to this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/NotificationTemplate/1.0",
         "id": "f4e88d66-fbaf-407b-947b-9ac687d96f37",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-03T13:12:03Z"
      },
      "name": "Credit Memo"
   },
   /* ... */
]

Notification Template Details¶

If the management system knows the APS ID of a notification template, it can request its full JSON representation as in the following example:

GET /aps/2/resources/f4e88d66-fbaf-407b-947b-9ac687d96f37

The notification template representation will look like the following response:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://www.odin.com/billing/NotificationTemplate/1.0",
      "id": "f4e88d66-fbaf-407b-947b-9ac687d96f37",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-03T13:12:03Z",
      "schema": "/aps/2/types/103",
      "package": {
         "id": "4bfbda2d-8e71-45ba-b3b6-ff7a2485a178",
         "href": "/aps/2/packages/4bfbda2d-8e71-45ba-b3b6-ff7a2485a178"
      }
   },
   "name": "Credit Memo"
}

Plan Categories ¶

The provider can create any number of plan categories used to group service plans for different purposes, mainly to assign them to the appropriate tax category.

List of Plan Categories¶

To get a list of all plan categories in BSS, the management system must issue the following request:

GET /aps/2/collections/service-plan-categories

The list of plan categories in the response will look like this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/ServicePlanCategory/1.0",
         "id": "51487aab-2e35-4624-9077-b9252fe23f36",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-06T13:38:36Z"
      },
      "description": {
         "en_US": "Testing the integration with the Product Initialization wizard"
      },
      "name": "User Management demo"
   },
   /* ... */
]

Plan Category Details¶

If the management system knows the APS ID of a plan category it can request its full JSON representation:

GET /aps/2/resources/51487aab-2e35-4624-9077-b9252fe23f36

The plan category representation will look like the following response:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://www.odin.com/billing/ServicePlanCategory/1.0",
      "id": "51487aab-2e35-4624-9077-b9252fe23f36",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-06T13:38:36Z",
      "schema": "/aps/2/types/106",
      "package": {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "description": {
      "en_US": "Testing the integration with the Product Initialization wizard"
   },
   "name": "User Management demo",
   "vendor": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/0ab950d1-abc9-4433-a87d-8ba009bf4bce",
         "id": "0ab950d1-abc9-4433-a87d-8ba009bf4bce"
      }
   }
}

Resources ¶

During application deployment, the provider creates resource types in OSS to represent the application services. Those resource types along with the service templates containing them are copied to BSS and after that are available through the BSS API considered here.

List of Resources¶

To get a list of all resources in BSS, the management system must issue the following request:

GET /aps/2/collections/bss-resources

The list of resources in the response will look like this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/Resource/1.0",
         "id": "9baec2f7-2995-4527-8299-806687b148f1",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T14:18:26Z"
      },
      "name": {
         "en_US": "User Management demo - VPS Mainstream Profile"
      }
   },
   {
      "aps": {
         "type": "http://www.odin.com/billing/Resource/1.0",
         "id": "ebd95c84-9dc0-43dd-8ad2-bbcb4fd73374",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T14:18:26Z"
      },
      "name": {
         "en_US": "User Management demo - Virtual Server"
      }
   },
   /* ... */
]

Resource Details¶

If the management system knows the APS ID of a resource it can request its full JSON representation:

GET /aps/2/resources/f4e88d66-fbaf-407b-947b-9ac687d96f37

The resource representation will look like the following response:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://www.odin.com/billing/Resource/1.0",
      "id": "ebd95c84-9dc0-43dd-8ad2-bbcb4fd73374",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T14:18:26Z",
      "schema": "/aps/2/types/104",
      "package": {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "name": {
      "en_US": "User Management demo - Virtual Server"
   }
}

Service Terms ¶

Every service plan must be bound to a service terms object.

List of Service Terms Objects¶

To get a list of all service terms in BSS, the management system must issue the following request

GET /aps/2/collections/service-terms

The list of service terms in the response will look like this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/ServiceTerms/1.0",
         "id": "8f9da85c-7e1c-443c-bac1-074cc21c2500",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T13:53:58Z"
      },
      "destroyAfterHold": false,
      "name": "Hosting Service Terms",
      "subGracePeriod": 10,
      "subHoldPeriod": 30,
      "trialDestroyAfterHold": true,
      "trialSubGracePeriod": 0,
      "trialSubHoldPeriod": 0
   },
   /* ... */
]

Service Terms Details¶

If the management system knows the APS ID of a service terms object it can request its full JSON representation:

GET /aps/2/resources/8f9da85c-7e1c-443c-bac1-074cc21c2500

The service terms representation will look like the following response:

HTTP/1.1 200 OK

{
   "aps": {
      "type": "http://www.odin.com/billing/ServiceTerms/1.0",
      "id": "8f9da85c-7e1c-443c-bac1-074cc21c2500",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T13:53:58Z",
      "schema": "/aps/2/types/107",
      "package": {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "destroyAfterHold": false,
   "name": "Hosting Service Terms",
   "subGracePeriod": 10,
   "subHoldPeriod": 30,
   "trialDestroyAfterHold": true,
   "trialSubGracePeriod": 0,
   "trialSubHoldPeriod": 0,
   "vendor": {
      "aps": {
         "link": "strong",
         "href": "/aps/2/resources/0ab950d1-abc9-4433-a87d-8ba009bf4bce",
         "id": "0ab950d1-abc9-4433-a87d-8ba009bf4bce"
      }
   }
}

Tax Categories ¶

A tax category is a very simple object that groups several service plans (through plan categories) and resources (through resource categories) to be included in a particular taxation algorithm. The algorithm takes into account the product category and the tax zone to calculate the taxes (for example, VAT) when selling those products in a particular regional zone.

List of Tax Categories¶

To get a list of all tax categories in BSS, the management system must issue the following request:

GET /aps/2/collections/tax-categories

The list of tax categories in the response will look like this:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "type": "http://www.odin.com/billing/TaxCategory/1.0",
         "id": "891950fe-9a1c-46ca-aba9-8fd860cb2be8",
         "status": "aps:ready",
         "revision": 2,
         "modified": "2017-08-04T13:53:59Z"
      },
      "name": "All products"
   },
   /* ... */
]

Tax Category Details¶

If the management system knows the APS ID of a tax category it can request its full JSON representation:

GET /aps/2/resources/891950fe-9a1c-46ca-aba9-8fd860cb2be8

The tax category representation will look like the following response:

HTTP/1.1 200 OK

{
   "aps":
   {
      "type": "http://www.odin.com/billing/TaxCategory/1.0",
      "id": "891950fe-9a1c-46ca-aba9-8fd860cb2be8",
      "status": "aps:ready",
      "revision": 2,
      "modified": "2017-08-04T13:53:59Z",
      "schema": "/aps/2/types/108",
      "package":
      {
         "id": "2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3",
         "href": "/aps/2/packages/2e9e3bfd-74cd-44ed-95e5-6dc22e51b1c3"
      }
   },
   "name": "All products",
   "vendor":
   {
      "aps":
      {
         "link": "strong",
         "href": "/aps/2/resources/0ab950d1-abc9-4433-a87d-8ba009bf4bce",
         "id": "0ab950d1-abc9-4433-a87d-8ba009bf4bce"
      }
   }
}

← Using APS REST API

Manage Prices →

CloudBlue Commerce API

Table Of Contents

Previous topic

Next topic

List Products¶

APS Types ¶

Service Plans ¶

List of Service Plans¶

All Service Plans¶

List of selected Service Plans¶

Service Plan Details¶

Pricing¶

Resource Dependencies¶

Notification Template ¶

List of Notification Templates¶

Notification Template Details¶

Plan Categories ¶

List of Plan Categories¶

Plan Category Details¶

Resources ¶

List of Resources¶

Resource Details¶

Service Terms ¶

List of Service Terms Objects¶

Service Terms Details¶

Tax Categories ¶

List of Tax Categories¶

Tax Category Details¶

CloudBlue Commerce API

Table Of Contents

Previous topic

Next topic

List Products¶

APS Types¶

Service Plans¶

List of Service Plans¶

All Service Plans¶

List of selected Service Plans¶

Service Plan Details¶

Pricing¶

Resource Dependencies¶

Notification Template¶

List of Notification Templates¶

Notification Template Details¶

Plan Categories¶

List of Plan Categories¶

Plan Category Details¶

Resources¶

List of Resources¶

Resource Details¶

Service Terms¶

List of Service Terms Objects¶

Service Terms Details¶

Tax Categories¶

List of Tax Categories¶

Tax Category Details¶

APS Types ¶

Service Plans ¶

Notification Template ¶

Plan Categories ¶

Resources ¶

Service Terms ¶

Tax Categories ¶