Billing API v1.0


Overview

The ionos Billing API is a REST API that can be used to retrieve information about resource usage and invoices.

What's New?

The following features have been added to the Billing API:

  • You can now request the traffic per virtual server and day by setting the MAC query parameter to "true".
  • Resellers can retrieve a list of their customers and contracts via /profile and access associated invoices.

Swagger

The most current information about available operations can be accessed at: Billing API Documentation - Swagger

Endpoint

The Billing API is securely accessed by making GET requests over a SSL/TLS link. The base endpoint URL is:

https://billingapi.profitbricks.com/

Authentication

For regular contracts, the Contract Holder will be able to authenticate with the Billing REST API. Users that have been granted Administrator permissions will also be able to authenticate against the Billing API.

Please Note: There will be a delay of less than 24 hours before a user who was recently assigned the Administrator role can successfully authenticate with the Billing API. This delay applies both to newly created users and existing users that are granted the Administrator role.

For contracts underneath a reseller account, the Contract Holder or Owner will be able to authenticate with the Billing API. The ability to grant access to other users associated with a reseller contract is not currently available.

The username, typically an e-mail address, and password need to be Base64 encoded and passed in using HTTP basic authentication. The curl utility will automatically handle this with the --user parameter. For example:

curl --include --request GET --user 'username@domain.tld:password' API_ENDPOINT

The Postman tool will handle this encoding automatically when Authorization -> Type -> Basic Auth is selected.

Information about Base64 encoding your credentials can be found in the Cloud API documentation. Look under Authorization.

Trying to access the API with incorrect credentials will result in a HTTP 403 error and a JSON response similar to this:

HTTP/1.1 403 Forbidden
{"httpStatus":401,"messages":[{"errorCode":"315","message":"Unauthorized"}]}

Trying to access the Billing API without using an account with the appropriate permissions will result in a 403 error and a JSON response.

HTTP/1.1 403 Forbidden
{"errCode":403,"message":"Main account needed."}

You may find a JSON parser, such as jq helpful if you are making requests from a command-line or shell using curl.

Operations

Profile

Sending a GET request to /profile is a good place to start. The response will contain the value(s) for contractId which is required for several other operations.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/profile

{
  "companies": [
    {
      "customerId": "string",
      "contractId": "string",
      "subsidiary": "US"
    }
  ]
}

Products

Using a valid contractId allows us to retrieve a list of products associated with a contract.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/products

{
  "metadata": {
    "contractId": "{contractId}",
    "customerId": "{customerId}",
    "subsidiary": "US"
  },
  "liability": "Please double check your contract for prices.",
  "products": [
    {
      "location": "EU",
      "meterId": "A01000",
      "meterDesc": "30d per static IP address",
      "unit": "30Days"
    },
...

Available Products.

IP Address, CPU Cores, RAM

Location MeterID Meter Description Unit
EU / US A01000 30d per static IP address 30 days
EU / US C02000 1h core Intel (+1 hyper-thread core) 1 hour
EU C010EU 1h core AMD - EU 1 hour
US C010US 1h core AMD - US 1 hour
EU CW10EU 1 MS core - per hour EU 1 hour
US CW10US 1 MS core - per hour US 1 hour
EU R010EU 1h per GB RAM - EU 1G * 1 hour
US R010US 1h per GB RAM - US 1G * 1 hour

Storage

Location MeterID Meter Description Unit
EU / US S01000 30d per 1 GB HDD Storage 1 GB * 30 days
EU / US S02000 30d per 1 GB SSD Storage 1 GB * 30 days
EU / US S03000 30d per 1 GB HDD Snapshot 1 GB * 30 days

S3 Object Storage

Location MeterID Meter Description Unit
EU S3AU1100 Count of PUT/COPY/POST/LOST S3 API request per 1,000 calls 1,000 calls
EU S3AU1200 Count of GET S3 API request per 10,000 calls 10,000 calls
EU S3AU1300 Count of DELETE S3 API request per 10,000 calls 10,000 calls
EU S3SU1100 30d per 1 GB S3 Object Storage for first 50 TB 1 GB x 30 days
EU S3SU1200 30d per 1 GB S3 Object Storage for next 450 TB 1 GB x 30 days
EU S3SU1300 30d per 1 GB S3 Object Storage above 500 TB 1 GB x 30 days

Traffic In/Out

Location MeterID Meter Description Unit
EU / US CTI1000 1 GB cumulative traffic inbound 1 GB
EU / US CTO1100 1 GB cumulative traffic outbound for first 10 TB 1 GB
EU / US CTO1200 1 GB cumulative traffic outbound for next 40 TB 1 GB
EU / US CTO1300 1 GB cumulative traffic outbound for next 100 TB 1 GB
EU / US CTO1400 1 GB cumulative traffic outbound for above 150 TB 1 GB

Traffic Usage

These values report total traffic for Virtual Data Centers and S3 Object Storage.

Location MeterID Meter Description Unit
EU / US TI1000 1 GB traffic inbound 1 GB
EU / US TO1000 1 GB traffic outbound 1 GB
EU S3TI1000 1 GB S3 total traffic inbound 1 GB
EU S3TO1000 1 GB S3 total traffic outbound 1 GB

License

Location MeterID Meter Description Unit
EU / US WL1000 1h per core AMD MS Windows license 1 hour
EU / US WL2000 1h per core Intel MS Windows license Intel (+1 hyper-thread core) 1 hour
EU / US WL3000 1h per core AMD MS Windows 2016 license 1 hour
EU / US WL4000 1h per core Intel MS Windows 2016 license Intel (+1 hyper-thread core) 1 hour

Usage

This operation returns usage details for the specific contractId for the current month. The period covered is listed at the beginning of the JSON response. For example, a request submitted on "2016-04-15" would return data from the 1st of April through the 14th of April 2016.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/usage

{
  "startDate": "2016-04-01",
  "endDate": "2016-04-14",

Previous usage data can be requested by appending ?period=YYYY-MM to the request URL. To request usage details for "January 2016":

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/usage?period=2016-01

By appending a valid datacenterId we can scope our usage request to a specific data center.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/usage/{datacenterId}

By default, the usage information will be from the beginning of the current month. Previous usage data for a specific virtual data center can be requested by appending ?period=YYYY-MM to the request URL.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/usage/{datacenterId}?period=2016-01

Invoices

Information about generated invoices is returned.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/invoices/

"invoices": [
{
  "id": "USA00000000",
  "date": "2015-01"
},

The value returned for "id" can be used in the next operation to get information about a specific invoice. Here is partial JSON output when requesting a specific invoiceId.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/invoices/{invoiceId}

{
  "metadata": {
    "contractId": "{contractId}",
    "customerId": "{customerId}",
    "subsidiary": "US",
    "postingPeriod": "2015-01",
    "createdDate": "{datetimestamp}",
    "startDate": "2015-01-01",
    "endDate": "2015-01-31",
    "invoiceId": "{invoiceId}"
  },
  "datacenters": [
    {
...

Traffic

Returns details on traffic (bandwidth) used by virtual data centers under a specific contractId. Traffic details are categorized as "Inbound" and "Outbound" and returned as daily totals in Bytes.

Please Note: The /traffic operations are currently under development and should be considered experimental.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/traffic

{
  "metadata": {
    "contractId": "{contractId}",
    "customerId": "{customerId}",
    "subsidiary": "US",
    "period": "2016-04",
    "unit": "Bytes"
  },
  "traffic": [
    "In/Out,VDC UUID,VDC Name,2016-04-01,2016-04-02,2016-04-03,2016-04-04,2016-04-05,2016-04-06,2016-04-07,2016-04-08,2016-04-09,2016-04-10,2016-04-11,2016-04-12,2016-04-13,2016-04-14,2016-04-15",
    "In,{data_center_id},{data_center_name},6555283,15443318,41617453,8756456,6542408,5537967,2452171,1838187,4121476,3392542,6001128,9431641,6567387,13722664,",
    "Out,{data_center_id},{data_center_name},11738400,26067674,18424715,15402326,13361558,10936700,4507092,4197609,9071560,7815692,10715590,17553149,12444569,27529012,"
    ]

If you would like the output to include a MAC column in addition to the UUID to help identify which server is generating the traffic, add the query parameter mac and set it to true.

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/traffic?mac=true

{
  "metadata": {
    "contractId": "{contractId}",
    "customerId": "{customerId}",
    "subsidiary": "US",
    "period": "2016-06",
    "unit": "Bytes"
},
"traffic": [
"In/Out,VDC UUID,VDC Name,MAC,2016-06-01,2016-06-02,2016-06-03,2016-06-04,2016-06-05,2016-06-06,2016-06-07,2016-06-08,2016-06-09,2016-06-10,2016-06-11,2016-06-12,2016-06-13,2016-06-14",
"In,{data_center_id},{data_center_name},02:01:61:b7:59:8a,5653116,1711644,2121063,20446357,14134643,2614548,17584495,9316156,5282514,2617379,5631471,6789185,2527722,",
"Out,{data_center_id},{data_center_name},02:01:61:b7:59:8a,8886897,1134528,2097299,21049105,25418771,2316760,17359558,16808637,8464120,3318111,10650240,11408014,3263951,",

Notice that a new column has been included the output after "VDC Name" called "MAC".

We have another operation available to see traffic details for a previous month.

/{contractId}/traffic/{period}

Use the format "YYYY-MM" for {period}.

An example request using curl and partial JSON output for traffic during March 2016:

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/traffic/2016-03

{
  "metadata": {
    "contractId": "{contractId}",
    "customerId": "{customerId}",
    "subsidiary": "US",
    "period": "2016-03",
    "unit": "Bytes"
  },
  "traffic": [
    "In/Out,VDC UUID,VDC Name,2016-03-01,2016-03-02,2016-03-03,2016-03-04,2016-03-05,2016-03-06,2016-03-07,2016-03-08,2016-03-09,2016-03-10,2016-03-11,2016-03-12,2016-03-13,2016-03-14,2016-03-15,2016-03-16,2016-03-17,2016-03-18,2016-03-19,2016-03-20,2016-03-21,2016-03-22,2016-03-23,2016-03-24,2016-03-25,2016-03-26,2016-03-27,2016-03-28,2016-03-29,2016-03-30,2016-03-31",

If you would like the output to include a MAC column in addition to the UUID to help identify which server is generating the traffic, add the query parameter mac and set it to true. For example, the request above can be modified to included the MAC information like this:

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/traffic/2016-03?mac=true

Evn / Itemized Data

This operation, /evn, will return itemized details grouped by virtual data center for the current period. An example of making the GET request is:

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/evn/

This operation also supports requesting data for a specific period, similar to the traffic operation. Use the format "YYYY-MM" for {period}. An example of making a GET request for a specific period (November 2016) is:

curl --request GET \
     --user 'username@domain.tld:password' \
     https://billingapi.profitbricks.com/{contractId}/evn/2016-11

Evn Example

We can use curl to retrieve detail data for Dec 2016 and store it in a local file to examine further.

curl --request GET --user 'username@domain.tld:password' https://api.profitbricks.com/billing/031764105/evn/2016-12 > evn_2016_Dec.json

Now that we have it saved, we will use jq to take a look at it.

jq -C . evn_2016_Dec.json  | more

The metadata returned indicates the period that we requested data for, along with a few other details.

{
 "metadata": {
   "contractId": "031764105",
   "customerId": "112463604",
   "subsidiary": "US",
   "period": "2016-12"
 },
 "datacenters": [

The next section, datacenters, has details about the resources we have provisioned. The individual resources are grouped by virtual data center.

{
      "vdcUUID": "0c054b8d-0917-4f89-85f0-bee68e171c00",
      "name": "Unnamed Data Center",
      "data": [
        {
          "resourceType": "NIC",
          "resourceUUID": "50de941c-af17-4302-8ef4-765c129c6f68",
          "intervalMin": 5058,
          "intervalDivisor": null,
          "from": "2016-12-28T11:42:48.101Z",
          "to": "2017-01-01T00:00:00.000Z",
          "itemStub": "TO1000",
          "value": "0",
          "valueDivisor": 1073741824,
          "additionalParameters": "02:01:76:cd:21:51"
        },
        {
          "resourceType": "NIC",
          "resourceUUID": "50de941c-af17-4302-8ef4-765c129c6f68",
          "intervalMin": 5058,
          "intervalDivisor": null,
          "from": "2016-12-28T11:42:48.101Z",
          "to": "2017-01-01T00:00:00.000Z",
          "itemStub": "TI1000",
          "value": "0",
          "valueDivisor": 1073741824,
          "additionalParameters": "02:01:76:cd:21:51"
        },
        {
          "resourceType": "SERVER",
          "resourceUUID": "fac10561-2c91-455e-81d5-5c1baebc1bb6",
          "intervalMin": 5056,
          "intervalDivisor": 60,
          "from": "2016-12-28T11:44:08.116Z",
          "to": "2017-01-01T00:00:00.000Z",
          "itemStub": "C010US",
          "value": "2",
          "valueDivisor": 1,
          "additionalParameters": "AMD_OPTERON"
        },
        {
          "resourceType": "SERVER",
          "resourceUUID": "fac10561-2c91-455e-81d5-5c1baebc1bb6",
          "intervalMin": 5056,
          "intervalDivisor": 60,
          "from": "2016-12-28T11:44:08.116Z",
          "to": "2017-01-01T00:00:00.000Z",
          "itemStub": "R01000",
          "value": "2048",
          "valueDivisor": 1024,
          "additionalParameters": "AMD_OPTERON"
        },
        {
          "resourceType": "STORAGE",
          "resourceUUID": "5fa36dcb-fb2f-48e4-8ff4-b67e750ba644",
          "intervalMin": 5057,
          "intervalDivisor": 43200,
          "from": "2016-12-28T11:43:57.361Z",
          "to": "2017-01-01T00:00:00.000Z",
          "itemStub": "S01000",
          "value": "10737418240",
          "valueDivisor": 1073741824,
          "additionalParameters": "HDD"
        }
      ]
    }

Looking through the example data you'll notice that we have some NICs, servers, and storage resources provisioned in this example virtual data center. Each has various properties including the resource's UUID. Of particular interest are the value and valueDivisor properties. Looking at the data returned for resourceType : STORAGE, and itemStub : S0100 in the example above, we would divide the value of 10737418240 by the valueDivisor of 1073741824 to get a result of 10, which is the size of the HDD in GB.

The last section of JSON data return is evnCSV. The first line contains column headers, and the remainder is populated with the relevant resource data.

"evnCSV": [
    "contractId,VDCUUID,VDCName,ResourceType,ResourceUUID,IntervalMin,IntervalDivisor,From,To,ItemStub,Value,ValueDivisor,Additional Parameters",
    "31764105,,,IP,005783bc-101f-4b28-84ff-3355416bed73,8,43200,2016-12-13T21:45:26.357Z,2016-12-13T21:53:23.250Z,A01000,1,1,",
    "31764105,,,IP,03445047-d029-48b6-931d-9a7b9cc1ca05,1,43200,2016-12-14T13:57:46.551Z,2016-12-14T13:58:10.963Z,A01000,2,1,",

You may find this format useful for importing into a spreadsheet for additional analysis.

** Please Note**: You may need to remove the double-quote from the beginning and end of each line of data in the evnCSV section in order to properly import it into your spreadsheet program. With the double-quotes in place, the spreadsheet may consider the entire line to be a single column.

Availability

Making a GET request to https://billingapi.profitbricks.com/intern/ping will return -1 if the Billing API is available.

curl https://billingapi.profitbricks.com/intern/ping
-1

If you supply valid credentials with the request, then a value of 1 is returned instead. (This example is also displaying the headers of the response.)

curl --include -X GET --user 'username@domain.tld:password' https://billingapi.profitbricks.com/intern/ping

HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Date: [datestamp] GMT
Connection: keep-alive
Content-Length: 1

1

Summary

If you have questions or comments, please contact your ionos Support team, or open a discussion in the ionos DevOps Community section of this site.