Manage Subscriptions¶

The BSS API allows external systems to manage subscriptions as described in this document.

In this document:

Subscriptions in BSS and OSS
Operations
List Subscriptions
Verify the Provisioning State
Get Subscription Details
Get Subscription Resources
Change the Subscription State
Update Custom Attributes of a Subscription

Subscriptions in BSS and OSS ¶

When subscribing to a service plan providing application services, a subscriber (normally, a customer) gets two tightly coupled subscriptions:

The BSS subscription is a contract between the sales vendor (the provider or a reseller) and the subscriber. It contains commercial data, such as subscription period, structured prices, and discounts. A BSS subscription is represented by an APS resource based on the BSSSubscription APS type.
The OSS subscription contains details about the services provided to the subscriber. It includes all resources (along with their limits and usage as configured in the corresponding service template) involved in the service provisioning process. On the APS bus, this subscription is represented by an APS resource based on the PASubscription APS type.

Note

BSS is the initiator of most operations with the coupled subscriptions. Therefore, the direct object in the subscription API operations is an APS resource representing a BSS subscription. Depending on the operation, the changes in a BSS subscription can affect the coupled OSS subscription.

If you know the APS ID of a BSS subscription (for example, 456808a0-b5a6-4092-ab67-b77e33743a07), you can find the coupled OSS subscription using the following request:

GET /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/paSubscription?select(aps.id,name)

The response looks as follows:

HTTP/1.1 200 OK

[
  {
    "aps": {
      "modified": "2019-03-12T12:11:09Z",
      "id": "4b9d0e6f-ba57-4c3d-9d28-e52b138787fb",
      "type": "http://parallels.com/aps/types/pa/subscription/1.0",
      "status": "aps:ready",
      "revision": 5
    },
    "name": "VPS Demo Services"
  }
]

Operations ¶

There are several operations that BSS exposes on the APS bus to manage subscriptions. Some of them require generating an order as considered in the Manage Orders document; this document explains other important operations.

An external management system can manage a typical subscription life cycle in the following ways:

Create a subscription: place a sales order as explained in the Sales Orders section of the Manage Orders document.
Get a list of subscriptions: there are various ways to do this, as explained in the List Subscriptions section.
Verify the provisioning state: call the provisioningState custom operation exposed by the PASubscription APS type.
Get details about a subscription: this is a typical operation from the CRUD set as explained in the Get Subscription Details section.
Put a subscription on hold and release it from hold: call the respective custom operations as explained in the Change the Subscription State section.

List Subscriptions ¶

You can search for a subscription or a list of subscriptions using various ways as in the following examples:

Get the full list of subscriptions:

GET /aps/2/collections/bss-subscriptions

Get all subscriptions of a customer using a Resource Query Language filter:
```
GET /aps/2/collections/bss-subscriptions?eq(account.aps.id,78560b5e-a762-4d52-b300-00543113e1d4)
```
The above request contains the APS ID of a customer.
Search for a subscription using a property with a unique value, for example, search it by name:
```
GET /aps/2/collections/subscriptions?like(name,*Demo*)
```

The response will look similar to the following:

HTTP/1.1 200 OK

[
   {
      "aps": {
         "modified": "2019-03-12T15:11:11Z",
         "id": "456808a0-b5a6-4092-ab67-b77e33743a07",
         "type": "http://www.odin.com/billing/Subscription/1.0",
         "status": "aps:ready",
         "revision": 13
      },
      "billingTerms": {
         "billingPeriod": {
            "duration": 1,
            "unit": "MONTHS"
         },
         "billingModel": "CHARGE_BEFORE_BILLING_PERIOD",
         "freezePrices": false,
         "autoRenewal": {
            "type": "DISABLED"
         }
      },
      "serviceGate": "PEMGATE",
      "trial": false,
      "nextBillDate": "2019-04-12",
      "subscriptionPeriod": {
         "duration": 3,
         "unit": "MONTHS"
      },
      "serviceStatus": "ACTIVE",
      "name": "VPS Demo Services",
      "lastBillDate": "2019-03-12",
      "subscriptionId": 1000001,
      "autoRenewEnabled": false,
      "startDate": "2019-03-12",
      "expirationDate": "2019-06-12",
      "status": "ACTIVE"
    }
]

If an external system needs to process a subscription bound to a certain order, get all subscriptions related to the order using the orderInfo custom operation of the order management service as explained in the Get List of Orders section of the Manage Orders document.

Verify the Provisioning State ¶

Provisioning of subscription resources in OSS takes some time. To verify whether the subscription is ready, call the provisioningState custom operation exposed by the PASubscription APS type, for example:

GET /aps/2/resources/4b9d0e6f-ba57-4c3d-9d28-e52b138787fb/provisioningState

If the subscription was provisioned successfully, the response will be:

HTTP/1.1 200 OK

{
   "state": "SUCCESS",
   "message": ""
}

Get Subscription Details ¶

To get the full representation of a subscription, use the GET method addressed to the subscription APS ID, for example:

GET /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07

If successful, the response will look similar to the following:

HTTP/1.1 200 OK

{
  "aps": {
    "schema": "/aps/2/types/156",
    "package": {
      "id": "92ccf5e8-fc07-4e7f-8875-5c19c8545870",
      "href": "/aps/2/packages/92ccf5e8-fc07-4e7f-8875-5c19c8545870"
    },
    "modified": "2019-03-12T13:19:54Z",
    "id": "456808a0-b5a6-4092-ab67-b77e33743a07",
    "type": "http://www.odin.com/billing/Subscription/1.0",
    "status": "aps:ready",
    "revision": 11
  },
  "subscriptionPeriod": {
    "duration": 3,
    "unit": "MONTHS"
  },
  "shutdownDate": "2019-03-12",
  "name": "VPS Demo Services",
  "billingTerms": {
    "billingPeriod": {
      "duration": 1,
      "unit": "MONTHS"
    },
    "freezePrices": false,
    "billingModel": "CHARGE_BEFORE_BILLING_PERIOD",
    "autoRenewal": {
      "type": "DISABLED"
    }
  },
  "vendor": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/2df1f8f0-39df-4f57-b810-e46e600eddab",
      "id": "2df1f8f0-39df-4f57-b810-e46e600eddab"
    }
  },
  "subscriptionId": 1000001,
  "serviceGate": "PEMGATE",
  "bssAccountInfo": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/66a19490-e738-4455-85b6-658b9780e764",
      "id": "66a19490-e738-4455-85b6-658b9780e764"
    }
  },
  "trial": false,
  "startDate": "2019-03-12",
  "serviceStatus": "STOPPED",
  "status": "TERMINATED",
  "terminationDate": "2019-04-11",
  "autoRenewEnabled": false,
  "paSubscription": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/4b9d0e6f-ba57-4c3d-9d28-e52b138787fb",
      "id": "4b9d0e6f-ba57-4c3d-9d28-e52b138787fb"
    }
  },
  "servicePlan": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/f282224a-68d0-413e-ab2b-5d836a1abd5d",
      "id": "f282224a-68d0-413e-ab2b-5d836a1abd5d"
    }
  },
  "account": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/78560b5e-a762-4d52-b300-00543113e1d4",
      "id": "78560b5e-a762-4d52-b300-00543113e1d4"
    }
  },
  "nextBillDate": "2019-03-12",
  "lastBillDate": "2019-03-12",
  "childSubscriptions": {
    "aps": {
      "link": "collection",
      "href": "/aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/childSubscriptions"
    }
  },
  "expirationDate": "2019-06-12"
}

Get Subscription Resources ¶

To get a list of resources in a subscription, call the getResources custom operation. Both BSS subscription and OSS subscription expose this operation.

If you call this operation on a BSS subscription:

GET /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/resources

The response only contains the resources sold through the service plan resource rates:

HTTP/1.1 200 OK

[
  {
    "resourceId": "bc88fcde-4235-49a9-8ef6-7fa886b48ef3",
    "internalResourceId": 1000060,
    "status": "INSTALLED",
    "name": {
      "en_US": "VPS Demo Services - Virtual Server"
    },
    "unitOfMeasureId": "unit",
    "unitOfMeasure": {
      "en_US": "unit"
    },
    "measurable": false,
    "showInCustomerPanel": true,
    "allowToModifyInTrial": false,
    "included": "1.0",
    "additional": "4.0",
    "ordered": "0.0",
    "min": "1.0",
    "usage": "0.0"
  }
]

If you call this operation on the coupled OSS subscription:

GET /aps/2/resources/4b9d0e6f-ba57-4c3d-9d28-e52b138787fb/resources

The response contains all resources as configured in the corresponding service template:

HTTP/1.1 200 OK

[
  {
    "id": "1000058",
    "resourceId": "74659c4e-cbde-4c12-b52a-be8285bd2cc7",
    "title": "VPS Demo Services - App REF",
    "apsId": "c13a9c5d-ae19-44d4-9318-63002f5007ba",
    "apsType": "http://aps-standard.org/samples/vpsdemo/cloud/1.0",
    "usage": 1,
    "limit": 1,
    "unit": "unit"
  },
  {
    "id": "1000059",
    "resourceId": "4ea29c65-1bed-4cce-a0c6-74dd5bfff201",
    "title": "VPS Demo Services - Management Environment",
    "apsId": "7ce76ba9-d9d9-4515-bff4-00cb91cdd766",
    "apsType": "http://aps-standard.org/samples/vpsdemo/context/1.0",
    "usage": 1,
    "limit": 1,
    "autoprovisioning": true,
    "unit": "unit"
  },
  {
    "id": "1000060",
    "resourceId": "bc88fcde-4235-49a9-8ef6-7fa886b48ef3",
    "title": "VPS Demo Services - Virtual Server",
    "apsType": "http://aps-standard.org/samples/vpsdemo/vps/1.0",
    "usage": 0,
    "limit": 5,
    "unit": "unit"
  }
]

Note

The VPS resource representation is returned by both of the above calls. Its APS ID (shown as the resourceId property) is the same in both subscriptions.

Change the Subscription State ¶

The PASubscription APS type exposes two custom operations to change a subscription state.

putOnHold switches a subscription to the Administrative Hold state, for example:

POST /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/putOnHold

{
   "reason": "ACCOUNT_OVERDUE",
   "comment": "Requested by the ERP system."
}

If successful, the response is:

HTTPS/1.1 204 No Content

If you request the subscription details, the response will show that the subscription status and the service status were changed:

{  //...
   "serviceStatus": "STOPPED",
   "status": "ADMINISTRATIVE_HOLD" /*,
   ... */
}

releaseFromHold returns a subscription to the Active state, for example:

POST /aps/2/resources/456808a0-b5a6-4092-ab67-b77e33743a07/releaseFromHold

{
   "reason": "OTHER",
   "comment": "The balance was restored. Requested by the ERP system."
}

If successful, the response is:

HTTPS/1.1 204 No Content

The subscription returns to the active status.

Update Custom Attributes of a Subscription ¶

You can update custom attributes of a subscription using the PUT method adressed to the subscription APS ID and specifying the data for the attributes property of the BSSSubscription APS type, for example:

POST /aps/2/resources/d0936d3c-4d13-4c0a-aa4b-4ef05f5e54b7

{
  "attributes": [
    {
      "attributeId": "PONumber",
      "value": "myponumber1"
    },
    {
      "attributeId": "PODetails",
      "value": "some_detail"
    }
  ]
}

If successful, the response is:

HTTP/1.1 200 OK

{
  "aps": {
    "id": "d0936d3c-4d13-4c0a-aa4b-4ef05f5e54b7",
    "type": "http://www.odin.com/billing/Subscription/1.0",
    "status": "aps:ready",
    "revision": 5,
    "modified": 1613625459175,
    "package": {
      "id": "5ec18d5a-cd86-4930-af1e-5e46504eb74a",
      "href": "/aps/2/packages/5ec18d5a-cd86-4930-af1e-5e46504eb74a"
    }
  },

   ...

  "lastBillDate": "2021-02-18",
  "attributes": [
    {
      "attributeId": "PONumber",
      "value": "myponumber1"
    },
    {
      "attributeId": "PODetails",
      "value": "some_detail"
    }
  ],
  "subscriptionId": 1000400,
  "autoRenewEnabled": false,
  "startDate": "2021-02-18",
  "account": {
    "aps": {
      "link": "weak",
      "href": "/aps/2/resources/da9ce04f-35e9-4675-a4e3-ca122b9b6c0b",
      "id": "da9ce04f-35e9-4675-a4e3-ca122b9b6c0b"
    }
  },
  "status": "ACTIVE",
  "expirationDate": "2031-02-18"
}

All new orders created for the updated subscription will be created with the changed custom attributes; orders created before the change will not be updated.

← Manage Orders

Get Resource Consumption →

CloudBlue Commerce API

Previous topic

Next topic

Manage Subscriptions¶

Subscriptions in BSS and OSS ¶

Operations ¶

List Subscriptions ¶

Verify the Provisioning State ¶

Get Subscription Details ¶

Get Subscription Resources ¶

Change the Subscription State ¶

Update Custom Attributes of a Subscription ¶