In this article we will go over a few of the more common billing related API questions we have received, and provide some REST examples on how to gather information from the SoftLayer API. Being able to understand the SoftLayer billing API can be key to planning your budget, as well as tracking usage and spending trends.
Before we begin I find it helpful to set some environment variables so that we don't have to provide our SoftLayer user and API key in every call. In your terminal run the following, substituting in your Portal username and API key:
export SOFTLAYER_USERNAME=<username> export SOFTLAYER_API_KEY=<apikey>
This is obviously an important thing to know, and one of the more basic billing queries you can make using the SoftLayer REST API. Here we use getNextInvoiceTotalAmount to retrieve the pre-tax total amount of an account's next invoice measured in US Dollars ($USD). The amount assumes no changes or charges occur between now and the time of billing.
curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk http://www.softlayersolution.com/rest/v3/SoftLayer_Account/getNextInvoiceTotalAmount.json
This API query is really handy for determining your current costs as well as providing insight on the benefit of hourly vs monthly costs. Long term you may find that the hourly server you are using would cost less if you migrated to a monthly pricing model. The use of Object Masks will help us narrow the output to just include the information we are looking for.
$ curl -sk "https://$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY@api.softlayer.com/rest/v3/SoftLayer_Virtual_Guest/<VSI_ID>/getBillingItem?objectMask=mask\[createDate,hoursUsed,hourlyRecurringFee,currentHourlyCharge\]"
The output will give us creation date of the VSI, the month to date charges, the hourly rate, and the total number of hours the device has been used so far since the start of the billing period:
{"createDate":"2015-12-16T15:50:05-06:00","currentHourlyCharge":".46","hourlyRecurringFee":".023","hoursUsed":"20"}To get more information about the meaning of these values, please see:
SoftLayer_Billing_Item
getInvoiceItems
getBillingItem
To find a billing item of a provisioned product you would use the getBillingItem call on the specific resource you are trying to locate. For instance if I wanted to find the Billing Item for one of my Endurance Storage volumes with an ID of 1234567 I would make the following API call:
curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk \ http://www.softlayersolution.com/rest/v3/SoftLayer_Network_Storage/1234567/getBillingItem
Along with the Billing Item ID you are looking for the output will give you information on the creation date, billing dates, recurring fees and if the item can be cancelled along with a host of other information.
{
"allowCancellationFlag": 1,
"cancellationDate": null,
"categoryCode": "storage_service_enterprise",
"createDate": "2015-11-17T12:14:14-06:00",
"cycleStartDate": "2015-12-04T00:07:24-06:00",
"description": "Endurance Storage",
"id": "87654321",
"laborFee": "0",
"laborFeeTaxRate": "0",
"lastBillDate": "2015-12-04T00:07:24-06:00",
"modifyDate": "2015-12-04T00:07:24-06:00",
"nextBillDate": "2016-01-04T00:00:00-06:00",
"oneTimeFee": "0",
"oneTimeFeeTaxRate": "0",
"orderItemId": 99999999,
"parentId": null,
"recurringFee": "0",
"recurringFeeTaxRate": "0",
"recurringMonths": 1,
"serviceProviderId": 1,
"setupFee": "0",
"setupFeeTaxRate": "0"
}The first step in the cancellation request would be to get the billing ID of the item you would like to cancel using the method in our previous example:
curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk \ http://www.softlayersolution.com/rest/v3/<SERVICE>/<ID>/getBillingItem
Once you have the correct Billing ID you can invoke the cancelService request. In this example we will be cancelling a Network Storage device with an ID of 12345678 and a billing ID of 9876543. The command should return the value 'true' to indicate that the item has been marked for cancellation.
curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk http://www.softlayersolution.com/rest/v3/SoftLayer_Billing_Item/9876543/cancelService true
If you are wanting to use the REST API to cancel a Bare Metal server you cannot use cancelService but rather you will need to invoke cancelItem and provide a cancellation reason.
If you need to associate a Billing ID with the service or item it corresponds to you can use getAssociatedBillingItem or getAssociatedParent along with an Object Mask. This can be used when parsing an invoice for a specific product or simply trying to determine a line item on an invoice to an actual SoftLayer product offering.
$ curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk "http://www.softlayersolution.com/rest/v3/SoftLayer_Billing_Item/1234321/getAssociatedParent?objectMask=mask\[id\]"
[{"id":987789}]]
curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk http://www.softlayersolution.com/rest/v3/SoftLayer_Billing_Item/1234321/getAssociatedBillingItem?objectMask=mask\[description,id,categoryCode\]"| python -m json.tool
{
"allowCancellationFlag": 1,
"cancellationDate": null,
"categoryCode": "storage_service_enterprise",
"createDate": "2015-04-29T06:55:46-07:00",
"cycleStartDate": "2015-12-04T00:07:21-06:00",
"description": "Endurance Storage",
"id": 987789,
"laborFee": "0",
"laborFeeTaxRate": "0",
"lastBillDate": "2015-12-04T00:07:21-06:00",
"modifyDate": "2015-12-04T00:07:21-06:00",
"nextBillDate": "2016-01-04T00:00:00-06:00",
"oneTimeFee": "0",
"oneTimeFeeTaxRate": "0",
"orderItemId": 99999999,
"parentId": null,
"recurringFee": "0",
"recurringFeeTaxRate": "0",
"recurringMonths": 1,
"serviceProviderId": 1,
"setupFee": "0",
"setupFeeTaxRate": "0"
}