CloudBlue Commerce API (DRAFT)
Table Of Contents
Product Identification¶
In sales processes, service plans are the products that are delegated to resellers. Therefore, you must first start with selecting and reading those products.
In this document:
Service Plans¶
In the platform, a service plan contains the following main components:
A link to a service template that contains all resources to be provided for sale through the service plan. Some of the resources are configured as resource rates so that customers pay for consumption of each resource individually.
A set of subscription periods that customers can subscribe to. A subscription period is measured in months or years.
Price configuration implies charging a customer subscription in a flexible way using various fees. Price configuration can be very simple, for example containing only fees for a subscription period without using any resource rates or more complex including the following fees:
For every subscription period, the plan can have a setup fee (one-time fee) and a recurring fee. The latter will charge a subscriber for every billing period, assuming that a subscription period contains several billing periods. Typically, a billing period is one month or one year (domain registration is an example of the latter).
Similarly, in a resource rate configuration, you will meet the setup and recurring fees for the respective resource usage. Usually, those fees are set up per resource unit. This can be an item, MB, GB, GB-h, or another type.
Discounts.
Tax components.
Typically, when working with reseller channels, the provider creates service plans and then delegate them to resellers with certain discounts. The provider can also sell a big amount of resources to resellers to allow them to create their own service plans based on those resources. A reseller can have sub-resellers and delegate service plans to them.
Get List of Service Plans¶
In terms of the integration system, every service plan is an APS resource with its own APS ID in the UUID format. It is based on the ServicePlan APS type. As explained in List Products, it is possible to get all service plans available for the reseller or to filter that list by some specific criteria as in the following examples.
Get All Service Plans¶
When sending a request for all service plan with the reseller’s credentials, the response will contain only the service plans delegated to the reseller as well as the service plans created by that reseller.
GET /aps/2/collections/service-plans
This is a sample response with some fields hidden for brevity:
HTTP/1.1 200 OK
[
{
"longDescription": {
"en_US": "User Management Demo - Assign services to end-users"
},
"aps": {
"modified": "2019-03-15T16:06:02Z",
"id": "51615892-655d-409d-a922-4423a8188b2e",
"type": "http://www.odin.com/billing/ServicePlan/1.1",
"status": "aps:ready",
"revision": 3
},
"resourceRates": [
{
"resourceId": "098a7165-8666-4f8d-8037-e34665e664e4",
"showInStore": true,
"measurable": false,
"showInCustomerPanel": true,
"sortNumber": 999,
"fees": {
"setup": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Mainstream Profile Setup"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"recurring": {
"price": {
"value": "1.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Mainstream Profile Recurring"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"overuse": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Mainstream Profile Overusage"
},
"showZeroPrice": false
},
"setupTiers": null,
"recurringTiers": null,
"overuseTiers": null
},
"publication": {
"store": {
"description": {
"en_US": ""
},
"priceText": {
"en_US": ""
}
}
},
"units": {
"included": "1.0",
"min": "1.0",
"max": "-1.0"
},
"display": {
"type": "DEFAULT"
},
"modifyInTrial": false
},
{
"resourceId": "2a27b06b-b18e-4609-87ca-5a21e961c143",
"showInStore": true,
"measurable": false,
"showInCustomerPanel": true,
"sortNumber": 999,
"fees": {
"setup": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Premium Profile Setup"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"recurring": {
"price": {
"value": "1.5",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Premium Profile Recurring"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"overuse": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Premium Profile Overusage"
},
"showZeroPrice": false
},
"setupTiers": null,
"recurringTiers": null,
"overuseTiers": null
},
"publication": {
"store": {
"description": {
"en_US": ""
},
"priceText": {
"en_US": ""
}
}
},
"units": {
"included": "0.0",
"min": "0.0",
"max": "-1.0"
},
"display": {
"type": "DEFAULT"
},
"modifyInTrial": false
}
],
"publication": {
"published": true
},
"name": {
"en_US": "User Management Demo"
},
"billingTerms": {
"pricingModel": "PM_FIXED_PRICE",
"period": {
"duration": 1,
"unit": "MONTHS"
},
"autorenewal": {
"days": 0,
"type": "DISABLED"
},
"recurringPricesEvery": "BILLING_PERIOD",
"model": "CHARGE_BEFORE_BILLING_PERIOD"
},
"planId": 10,
"shortDescription": {
"en_US": "User Management Demo"
},
"subscriptionPeriods": [
{
"autoRenewalPeriod": {
"unit": "MONTHS",
"duration": 1
},
"numberOfBillingPeriods": 1,
"trial": false,
"defaultPeriod": false,
"fees": {
"setup": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Setup"
},
"showZeroPrice": false
},
"recurring": {
"price": {
"value": "4.25",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Recurring"
},
"showZeroPrice": false
},
"renewal": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Renewal"
},
"showZeroPrice": false
},
"deposit": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Deposit"
},
"showZeroPrice": false
}
},
"refund": {
"nonRefundableAmount": {
"value": "0.0",
"code": "USD"
},
"fullRefundPeriodInDays": 0,
"afterRefundPeriod": "NO"
},
"sortOrder": null,
"active": true
},
{
"autoRenewalPeriod": {
"unit": "MONTHS",
"duration": 3
},
"numberOfBillingPeriods": 3,
"trial": false,
"defaultPeriod": false,
"fees": {
"setup": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Setup"
},
"showZeroPrice": false
},
"recurring": {
"price": {
"value": "4.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Recurring"
},
"showZeroPrice": false
},
"renewal": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Renewal"
},
"showZeroPrice": false
},
"deposit": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Deposit"
},
"showZeroPrice": false
}
},
"refund": {
"nonRefundableAmount": {
"value": "0.0",
"code": "USD"
},
"fullRefundPeriodInDays": 0,
"afterRefundPeriod": "RECURRING"
},
"sortOrder": null,
"active": true
}
]
}
]
Get Filtered List of Service Plans¶
When retrieving service plans, it is important to only retrieve plans which are published in order to avoid presenting unavailable plans to customers. With the following RQL statement, the non-published service plans shown in the previous response will be filtered out.
GET /aps/2/collections/service-plans?eq(publication.published,true)
Get Service Plan Details¶
Once the external system identifies the required service plan, it can retrieve that service plan separately when needed:
GET /aps/2/resources/51615892-655d-409d-a922-4423a8188b2e
The response will contain the JSON representation of the required service plan as in the following example:
HTTP/1.1 200 OK
{
"aps": {
"schema": "/aps/2/types/155",
"package": {
"id": "92ccf5e8-fc07-4e7f-8875-5c19c8545870",
"href": "/aps/2/packages/92ccf5e8-fc07-4e7f-8875-5c19c8545870"
},
"modified": "2019-03-15T16:06:02Z",
"id": "51615892-655d-409d-a922-4423a8188b2e",
"type": "http://www.odin.com/billing/ServicePlan/1.1",
"status": "aps:ready",
"revision": 3
},
"billingTerms": {
"pricingModel": "PM_FIXED_PRICE",
"period": {
"duration": 1,
"unit": "MONTHS"
},
"autorenewal": {
"days": 0,
"type": "DISABLED"
},
"recurringPricesEvery": "BILLING_PERIOD",
"model": "CHARGE_BEFORE_BILLING_PERIOD"
},
"category": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/2a1b0527-a50f-43aa-ab05-625fdb8d764a",
"id": "2a1b0527-a50f-43aa-ab05-625fdb8d764a"
}
},
"shortDescription": {
"en_US": "User Management Demo"
},
"publication": {
"published": true
},
"name": {
"en_US": "User Management Demo"
},
"longDescription": {
"en_US": "User Management Demo - Assign services to end-users"
},
"serviceTerms": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/cceb8688-efff-407b-88ed-7a4b8edc0c2a",
"id": "cceb8688-efff-407b-88ed-7a4b8edc0c2a"
}
},
"resourceRates": [
{
"resourceId": "098a7165-8666-4f8d-8037-e34665e664e4",
"showInStore": true,
"measurable": false,
"showInCustomerPanel": true,
"sortNumber": 999,
"fees": {
"setup": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Mainstream Profile Setup"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"recurring": {
"price": {
"value": "1.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Mainstream Profile Recurring"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"overuse": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Mainstream Profile Overusage"
},
"showZeroPrice": false
},
"setupTiers": null,
"recurringTiers": null,
"overuseTiers": null
},
"publication": {
"store": {
"description": {
"en_US": ""
},
"priceText": {
"en_US": ""
}
}
},
"units": {
"included": "1.0",
"min": "1.0",
"max": "-1.0"
},
"display": {
"type": "DEFAULT"
},
"modifyInTrial": false
},
{
"resourceId": "2a27b06b-b18e-4609-87ca-5a21e961c143",
"showInStore": true,
"measurable": false,
"showInCustomerPanel": true,
"sortNumber": 999,
"fees": {
"setup": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Premium Profile Setup"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"recurring": {
"price": {
"value": "1.5",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Premium Profile Recurring"
},
"showZeroPrice": false,
"chargePerUnit": true
},
"overuse": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "User Management Demo - VPS Premium Profile Overusage"
},
"showZeroPrice": false
},
"setupTiers": null,
"recurringTiers": null,
"overuseTiers": null
},
"publication": {
"store": {
"description": {
"en_US": ""
},
"priceText": {
"en_US": ""
}
}
},
"units": {
"included": "0.0",
"min": "0.0",
"max": "-1.0"
},
"display": {
"type": "DEFAULT"
},
"modifyInTrial": false
}
],
"vendor": {
"aps": {
"link": "strong",
"href": "/aps/2/resources/78ee642d-3b8a-48f1-af12-90563e38bd18",
"id": "78ee642d-3b8a-48f1-af12-90563e38bd18"
}
},
"resources": {
"aps": {
"link": "collection",
"href": "/aps/2/resources/51615892-655d-409d-a922-4423a8188b2e/resources"
}
},
"subscriptionPeriods": [
{
"autoRenewalPeriod": {
"unit": "MONTHS",
"duration": 1
},
"numberOfBillingPeriods": 1,
"trial": false,
"defaultPeriod": false,
"fees": {
"setup": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Setup"
},
"showZeroPrice": false
},
"recurring": {
"price": {
"value": "4.25",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Recurring"
},
"showZeroPrice": false
},
"renewal": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Renewal"
},
"showZeroPrice": false
},
"deposit": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Deposit"
},
"showZeroPrice": false
}
},
"refund": {
"nonRefundableAmount": {
"value": "0.0",
"code": "USD"
},
"fullRefundPeriodInDays": 0,
"afterRefundPeriod": "NO"
},
"sortOrder": null,
"active": true
},
{
"autoRenewalPeriod": {
"unit": "MONTHS",
"duration": 3
},
"numberOfBillingPeriods": 3,
"trial": false,
"defaultPeriod": false,
"fees": {
"setup": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Setup"
},
"showZeroPrice": false
},
"recurring": {
"price": {
"value": "4.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Recurring"
},
"showZeroPrice": false
},
"renewal": {
"price": {
"value": "2.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Renewal"
},
"showZeroPrice": false
},
"deposit": {
"price": {
"value": "0.0",
"code": "USD"
},
"msrp": null,
"description": {
"en_US": "@@Subscription_Plan_Name@ Deposit"
},
"showZeroPrice": false
}
},
"refund": {
"nonRefundableAmount": {
"value": "0.0",
"code": "USD"
},
"fullRefundPeriodInDays": 0,
"afterRefundPeriod": "RECURRING"
},
"sortOrder": null,
"active": true
}
],
"parentServicePlan": {
"aps": {
"link": "weak",
"href": "/aps/2/resources/d78f87ee-780b-4ebe-b5ae-d6fb82c0c79e",
"id": "d78f87ee-780b-4ebe-b5ae-d6fb82c0c79e"
}
},
"serviceTemplate": {
"aps": {
"link": "weak",
"href": "/aps/2/resources/890f866d-0820-4772-a567-d152add0ce16",
"id": "890f866d-0820-4772-a567-d152add0ce16"
}
},
"planId": 10
}