Billing-related API

[Update: June 17, 2016]

1. Overview

With SAKURA Cloud API provided by SAKURA Cloud, it is possible to not only operate resources, but also obtain billing-related information, including billing amounts and detailed statements of use of each resource. By using this API,

  • it becomes possible to automatically create a bill for each end user while adding a commission to the fee for SAKURA Cloud,
  • meticulously analyze the usage of resources, including the numbers of servers and disks used and usage time, based on previous billing records,
  • and create an original billing alert function based on the ratio with respect to traffic volume, without using billing alert function, which can only set a simple billing threshold,

to expand the range of automation and labor saving in the billing process.

For general information about how to use SAKURA Cloud API, etc., please refer to API document .
Information about billing-related functions, endpoints, and samples is available in this page .

API URL

A base URL for using a billing-related API is arbitrarily chosen from the following.

https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/is1a/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/is1b/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/tk1v/api/system/1.0/

*The version of the base URL is different from that of the API used for controlling resources. Please be careful.
*Billing information is put together for each account regardless of zone, and so the same results will be given no matter which URL you send a request to.

Cautions

  • The billing data for the month concerned will be created on the following day, and the data on the determined billing amount for each month will be created on the first day of the following month.
  • If billing data have not been updated, please obtain the data again after a while.
  • In order to execute a billing-related API, it is necessary to have an API key authorized to access “Billing Information” and have an access level for “View Resources” or higher. For details, please refer to page of access levels

2. Example of use

An API key exclusively for acquiring new billing information will be issued, and an example of use for obtaining the detailed statement of billing via the API will be described.

The parameters used in the procedure are as follows.

Parameter Explanation
Member ID This is a member ID for SAKURA Internet.
(e.g.) nnn00000
Billing statement ID This is an ID for identifying a billing statement numbered in each month. Billing statement ID is issued for each account.
(e.g.) 000000000
Access token This is the access token of an API key.
(e.g.) ACCESS_TOKEN is displayed.
Access token secret This is the access token secret of an API key.
(e.g.) ACCESS_TOKEN_SECRET is displayed.

Creation of an API key

Click [Settings] at the top of the control panel.

Click [API Key] in the submenu of settings. The API management window will be displayed, and the list of created API keys will be displayed if any.

This time, click [Add] in the upper right, to create a new API key for obtaining billing information.

For giving the minimum authority as an API key exclusively for obtaining billing information, please check only “View Resources” for the access level and “Billing Information” for the access permission for other services, and then click [Create] (Enter a name to easily identify the API key you created this time in the blank for names or explanations).

The created API key will be displayed in the list. Double-click the API key.

The details screen will be displayed. [ACCESS_TOKEN] and [ACCESS TOKEN SECRET], which are required for actual API access, will be displayed.

*If there are multiple accounts, it is necessary to create an API key for each account.

Acquisition of the resource ID of an account

Your own account ID is necessary for checking billing information with an API. The account ID is checked in advance with the following operation. In the following command examples, the curl command sends an inquiry to the API server, and the jq command modifies response results in an understandable manner.

$ curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status | jq .

The response from the API server is as follows.

{
     "is_ok": true,
     "Member": {
             "Errors": null,
             "Code": "xxx000001",
             "Class": "sakura"
     },
     "User": null,
     "AuthMethod": "apikey",
     "AuthClass": "account",
     "Permission": "create",
     "ExternalPermission": "bill",
     "RESTFilter": null,
     "IsAPIKey": true,
     "OperationPenalty": "none",
     "Account": {
             "Code": "billTest",
             "Name": "APIテスト用",
             "Class": "account",
             "ID": "000000526782"
     }
}

The numerical characters of

“ID”: “000000526782”

at the end of this response indicates an account ID.

*The jq command can narrow down keys as follows. With this function, only an account ID is outputted, so that it can be checked easily.

$ curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status | jq -c " .Account "

The response from the API server is as follows.

{"Code":"billTest","Name":"APIテスト用","Class":"account","ID":"000000526782"}

Check previous billing records.

Previous billing records will be displayed. For the endpoint of the API, /bill/by-contract/:accountid will be used.

$ curl --user "ACCESS_TOKEN":"ACCESS_TOKEN_SECRET" https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/bill/by-contract/112700526782 | jq .

The response from the API server is as follows.

{
     "is_ok": true,
     "ResponsedAt": "2016-06-01T13:33:13+09:00",
     "Count": 12,
     "Bills": [{
                     "PaymentClassID": 200,
                     "PayLimit": "2016-06-30T00:00:00+09:00",
                     "Paid": false,
                     "MemberID": "xxx000001",
                     "Date": "2016-06-10T00:00:00+09:00",
                     "BillID": 13481639,
                     "Amount": 4330
             }, {
                     "PaymentClassID": 200,
                     "PayLimit": "2016-05-31T00:00:00+09:00",
                     "Paid": true,
                     "MemberID": "xxx000001",
                     "Date": "2016-05-10T00:00:00+09:00",
                     "BillID": 13327977,
                     "Amount": 4330
             },
             .....
     }
}

The details of major keys included in the response are as follows.

Key name Explanation
Date Billing date in the form of ISO 8601.
(e.g.) 2016-05-10T00:00:00+09:00
Amount Billing amount (tax included in yen).
(e.g.) 4330
BillID Billing statement ID. It is also used for seeing the details.
(e.g.) 13327977

Obtain a detailed statement of billing from billing statement ID.

When a detailed statement of billing is obtained from billing statement ID, /billdetail/:membercd/:billno is used for the endpoint of the API.

The parameters used for sending an inquiry are as follows.

URL parameter Explanation
membercd Member ID of a billing statement you want to obtain
billno Billing statement No. to be processed

The parameters will be substituted with the member ID and the billing statement No. that has been confirmed.

$ curl --user "ACCESS_TOKEN":"ACCESS_TOKEN_SECRET" https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/000000000 | jq .

The response from the API server is as follows.

{
     "is_ok": true,
     "ResponsedAt": "2016-06-01T13:39:54+09:00",
     "Count": 3,
     "BillDetails": [{
             "Usage": 2592000,
             "ServiceClassID": 50000,
             "Index": 1,
             "ContractID": "112700526782",
             "Amount": 0
     }, {
             "Usage": 2592000,
             "ServiceClassID": 50118,
             "Index": 2,
             "ContractID": "112700654736",
             "Amount": 108
     }, {
             "Usage": 2474113,
             "ServiceClassID": 50295,
             "Index": 3,
             "ContractID": "112700675125",
             "Amount": 540
     }]
}

The details of major keys included in the response are as follows.

Items of a detailed statement of billing Explanation
Usage Time [sec] and amount of usage for each detailed item
ServiceClassID Contract ID for a detailed statement
Index Sequence in the same detailed information
ContractID Contract ID for details
Amount Billing amount for each detailed item

Obtain a detailed statement of billing in the CSV format.

This is the procedure for obtaining a detailed statement of billing in the CSV format. A detailed statement of billing in the CSV format can be obtained from the display screen of billing information displayed after clicking “Billing Information” at the upper right of the control panel.

$ printf "`curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/000000000/csv | jq .Body`"

The response from the API server is as follows.

""連番","請求書番号","利用年月","支払いステータス","会員ID","アカウントコード","リソースID","商品ID","商品名","ゾーンID","ゾーン名","日数","時間","商品金額(税別)","税金","リソース名"
"1","000000000","2015/09","入金済み","xxx000001","payTest","112700526782","50000","さくらのクラウド",,,"30","0","0","0",
"2","000000000","2015/09","入金済み","xxx000001","payTest","112700654736","50118","ISOイメージアップロード/5GB","is1b","石狩第2ゾーン","30","0","100","8","名称未設定 ISOイメージ 14ef10fedac"
"3","000000000","2015/09","入金済み","xxx000001","payTest","112700675125","50295","GSLB",,,"28","16","500","40","テスト"

The content of each field is as follows.

Sequential number Sequential number in the same billing statement No.
Billing statement No. A billing statement is issued for each account code in member ID. All zones are included.
Date of use Date of use for billing
Payment status There are three kinds of status: Unpaid, Paid, and Pending. In the month in which fees are not charged, the status is recognized as Pending.
Member ID Member ID
Account code Account code
Resource ID This is a unique value allocated to each used resource. When combined with a billing statement No., it becomes a unique key.
Product ID This is an ID allocated to each product. Even for the same product, product ID varies according to zone. Please obtain a product name from the rate list.
Product name A product name will be inputted. Even for the same product name, product ID varies according to zone, etc. Please be careful.
Zone ID This is an ID allocated to each zone. The blank will not be filled in, in the case of global resources.
Zone name The zone name allocated to each zone will be inputted. The blank will not be filled in, in the case of global resources.
Days The number of days of use will be displayed. In the case of products for which a billing amount is calculated on a per diem basis, if you use a product for 20 or more days, a monthly charge will be applied. The billing amount for a month concerned is calculated with the reference time being 0:00 of the date of downloading.
Hours The remainder obtained after dividing the number of hours of use by 24 will be displayed. The billing amount for a month concerned is calculated with the reference time being 0:00 of the date of downloading.
Product price (tax excluded) Product price not including tax
Tax Consumption tax amount
Resource name A name you have determined for each resource will be inputted. For example, a server name is inputted for each server.

3. Acquisition of the price list

Authority required for access

The access level set for the API needs to be for view or higher.

Cautions

The price list available via the API varies according to the account connected to the API.
It is also possible to obtain the prices of services offered to individual customers that are not included in the price list in the control panel via the API, in addition to the prices of services for which the price list is offered that can be obtained via the control panel.

For details, please see SAKURA Cloud API document.

For reference: Example of invocation with Curl (Linux)

# APIキーによる認証を行わない場合
curl -H "X-Requested-With:XMLHttpRequest" \
    https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/public/price.json
# APIキーによる認証を行う場合
curl --user "Access Token":"Access Token Secret" \
    https://secure.sakura.ad.jp/cloud/zone/is1a/api/cloud/1.1/public/price.json