getInvoice.pl

#!/usr/bin/perl
# Retrieve and analyze a single invoice record
#
# Print a simple report containing information about a single SoftLayer invoice:
# * The invoice's id number and creation date
# * The amount billed in the invoice
# * A list of all items billed for in the invoice, their child items, and their
#   prices.
# * Note whether or not the item billed is for an existing server on your
#   SoftLauer account.
#
# See below for more information.
#
# This assumes you're using the SoftLayer API Perl client
# <http://github.com/softlayer/softlayer-api-perl-client>.
#
# Important manual pages:
# http://sldn.softlayer.com/reference/services/SoftLayer_Billing_Invoice
# http://sldn.softlayer.com/reference/services/SoftLayer_Billing_Invoice/getObject
# http://sldn.softlayer.com/reference/services/SoftLayer_Billing_Invoice_Item
# http://sldn.softlayer.com/reference/datatypes/SoftLayer_Billing_Item
#
# License: http://sldn.softlayer.com/article/License
# Author: SoftLayer Technologies, Inc. <[email protected]>

# Set this to the path of the SoftLayer API Perl client.
use lib '/path/to/client/';

use SoftLayer::API::SOAP;
use strict;

# Your SoftLayer API username and key.
#
# Generate an API key at the SoftLayer Customer Portal:
# https://manage.softlayer.com/Administrative/apiKeychain
my $apiUsername = 'set me!';
my $apiKey = 'set me too!';

# Your invoice's id number.
#
# Use the getInvoices() method in the SoftLayer_Account API service to get a
# list of your account's invoices if you don't know which invoice you wish to
# view.
my $invoiceId = 1234;

# Connect to the SoftLayer_Billing_Invoice API service.
my $client = SoftLayer::API::SOAP->new('SoftLayer_Billing_Invoice', $invoiceId, $apiUsername, $apiKey);

# Retrieve charge, line item, and resource information along with our invoice
# record.
#
# Every invoice record has a number of invoice line items associated with it.
# These line items represent the individual service you're paying for, a server,
# a load balancer, a virtual dedicated rack, or anything else you can purchase
# from SoftLayer. Invoice items may have child invoice items relating to the
# specific components or upgrades contained within the service you've purchased,
# such as RAM, hard drives, or dedicated rack members.
#
# Invoice items are created from your server and services' billing items at
# the time your invoice is created on your billing anniversery date. Every
# invoice item is related back to that billing item, and a billing item may be
# directly related to the resource that you're paying for.
#
# An object mask in your API call can retrieve all of this relational
# information (and much much more if you wish) with a single call.
$client->setObjectMask({
    'invoiceTopLevelItems' => {
        'totalOneTimeAmount' => {},
        'totalRecurringAmount' => {},
        'totalOneTimeTaxAount' => {},
        'totalRecurringTaxAmount' => {},
        'children' => {},
        'billingItem' => {
            'resource' => {},
        },
    },
    'invoiceTotalOneTimeAmount' => {},
    'invoiceTotalRecurringAmount' => {},
    'invoiceTotalOneTimeTaxAmount' => {},
    'invoiceTotalRecurringTaxAmount' => {},
});

# Retrieve the invoice record.
my $invoice = $client->getObject();

# Error out if there was an error getting the invoice.
if ($invoice->fault) {
    die 'There was an error retrieving your invoice. ' . $invoice->faultstring;
}

$invoice = $invoice->result;

# Print a simple report header with invoice id, creation date, and total
# charges.
print <<EOT;
Invoice $invoice->{id}, Created $invoice->{createDate}
Total Amount: \$$invoice->{invoiceTotalOneTimeAmount} One-time + \$$invoice->{invoiceTotalOneTimeTaxAmount} tax / \$$invoice->{invoiceTotalRecurringAmount} Recurring + \$$invoice->{invoiceTotalRecurringTaxAmount} tax

EOT

# Process top-level invoice line items. Loop through the {invoiceTopLevelItems}
# property in our invoice to get what we need.
my $topLevelInvoiceItems = $invoice->{invoiceTopLevelItems};

for my $i (0 .. $#{$topLevelInvoiceItems}) {
    my $topLevelInvoiceItem = $topLevelInvoiceItems->[$i];

    # Print a simple header for each top-level invoice line item. Include the
    # hostname and domain name if the line item is for a server.
    print $topLevelInvoiceItem->{description};

    if ($topLevelInvoiceItem->{categoryCode} eq 'server') {
        print ": " . $topLevelInvoiceItem->{hostName} . "." . $topLevelInvoiceItem->{domainName};
    }

    print ": \$" . $topLevelInvoiceItem->{totalOneTimeAmount} . " One time / \$" . $topLevelInvoiceItem->{totalRecurringAmount} . " Recurring \n";

    # Some line items may exist for servers that are no longer on your account.
    # Each invoice item is created from a billing item associated with your
    # SoftLayer servers and services. This billing item is contained in the
    # {billingItem} property in your invoice item. If your billing item is
    # created for a resource that still exists (eg. for hardware still on your
    # account) then that billing item's {resource} property will be populated
    # with that resource's information.
    #
    # A billing item resource can be anything from a server to a cloud instance
    # to a load balancer to anything else purchased from SoftLayer, but for this
    # example we'll only note line items that exist for dedicated servers that
    # are still on our account.
    if ($topLevelInvoiceItem->{categoryCode} eq 'server' && $topLevelInvoiceItem->{billingItem}->{resource} ne undef) {
        print "Matched to existing hardware record " . $topLevelInvoiceItem->{billingItem}->{resource}->{id} . "\n";
    }

    # Loop through the line item's child items. Invoice items exist in a
    # parent-child relationship. Upgrades and addons for servers each have their
    # own child billing items to the server's billing item, and likewise have
    # child invoice items to the server's invoice items.
    my $childInvoiceItems = $topLevelInvoiceItem->{children};

    for my $j (0 .. $#{$childInvoiceItems}) {
        my $childInvoiceItem = $childInvoiceItems->[$j];

        # Print the child item's description, its one-time charge, and its
        # recurring fee.
        print " - " . $childInvoiceItem->{description} . ": \$" . $childInvoiceItem->{oneTimeFee} . " / \$" . $childInvoiceItem->{recurringFee} . "\n";
    }

    print "\n";
}