Getting started with REST and the SoftLayer Billing API

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>

How do I find out what my next bill will be?

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 https://api.softlayer.com/rest/v3/SoftLayer_Account/getNextInvoiceTotalAmount.json

How much has an hourly device cost me month-to-date?

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"}

Additional Resources

To get more information about the meaning of these values, please see:
SoftLayer_Billing_Item
getInvoiceItems
getBillingItem

How do I find a billing item from a provisioned product?

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 \
https://api.softlayer.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"
}

How do I cancel an item?

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 \
https://api.softlayer.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 https://api.softlayer.com/rest/v3/SoftLayer_Billing_Item/9876543/cancelService
 
true

Note

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.

How do I find a provisioned product from a billing item?

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 "https://api.softlayer.com/rest/v3/SoftLayer_Billing_Item/1234321/getAssociatedParent?objectMask=mask\[id\]"
 
[{"id":987789}]]
 
curl --user "$SOFTLAYER_USERNAME:$SOFTLAYER_API_KEY" -sk https://api.softlayer.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"
}