SORACOM Developers

Documents

Detailed Billing Information CSV

Introduction

Usage fees for SORACOM services are calculated and billed based on a billing period that starts at the beginning of the month and finishes at the end of the month (UTC). The total billing amounts can be verified from the console; however, you can also use the console or the API to output data in CSV format containing a detailed breakdown of all the usage fees. This document shall now explain how to download CSV data containing detailed billing information.

Download Detailed Billing Information CSV Using the Console

You can download detailed billing information for the most recent month from “This Month’s Usage Fees” under the Billing Information tab.

recent month csv

recent month csv

This CSV data corresponds to the most recent month, and is therefore updated over time.

CSV data from previous months can be downloaded by clicking on the months that you are interested in under “Past Usage Fees,” and then clicking on the download button at the bottom of the screen. Get CSV from previous months1 Get CSV from previous months1

Download Detailed Billing Information CSV Using the API

The most recent month’s billing information can be obtained using the exportLatestBilling API of the API Reference. For billing information of previous months, please use the exportBilling API.

Based on the current API specification, when you are at the beginning of a month, the CSV that can be obtained using exportLatestBilling corresponds to that month. Until the closing of accounts has taken place at the beginning of the month (i.e. the processing of account re-calculations for the previous month) and those billing figures have been finalized, you will not be able to download data for the previous month using the exportBilling API. Closing of accounts at the beginning of the month is generally completed within 1 to 3 business days from the start of the month.

CSV Encoding

CSV files are UTF-8 encoded (including BOMs).

CSV File Structure

CSV files have the following structure.

CSV structure

See below for a description of each data item.

First Row: Header

The header row contains a number of data items. These are broadly divided into “Amount Data Items” and “Tag/Group Data Items,” and the Amount Data Items are always output before the Tag/Group Data Items. Both Amount Data Items and Tag/Group Data Items are variable, so please refer to the section titled “Important Notes on CSV Parsing” when reading in the data using a program.

The data items displayed under “Amount Data Items” are as shown below.

The “Tag/Group Data Items” include the tag name and group name configured for each SIM. For example, if you assign a tag name/group name as shown, the data item names and records are output as follows.

name,tag1,group:groupId,group:name
MySIM,foo,d674d68e-da8a-44f6-8868-51d1f069bc06,Group1

If a SIM has been assigned a tag, or if it is set to belong to a group, the output for that SIM record will include the tag name/group ID or name. These values can then be used to make aggregate calculations for a particular tag value or group name.

Second Row Onward: Data Record Rows

The second row onward includes the actual data rows. The records are divided into “Billing Records” and “Discount Records,” and the Billing Records are always output before the Discount Records.

Billing records are created per IMSI/VPGID, day, and billing data item; and quantity and amount are totaled per day (UTC). Also, if the IMSI or VPG have been assigned tags, their values are output in the Tag/Group Data Items section.

Discount records include data items that are discounted from the usage fees due to free allowances and coupons. The “date” in the discount records specifies the applicable month for the discount. The “amount” specifies the discount amount as a negative number.

CSV data does not include data items corresponding to consumption tax or the total invoiced amounts, so if you want to match the records up with the invoiced amounts, you will need to calculate the total of all the values in “amount,” apply consumption tax, and round up any decimal figures.

Important Notes on CSV Parsing

CSV data is encoded in UTF-8 and includes BOMs, so please make sure to read in the data as UTF-8.

If a tag/group value has a comma (,), the value is enclosed within double quotes. If it has a double quote (“), it is escaped using double quotes. To use these strings, please make sure to use a CSV parser capable of dealing with escaped data.

As the data items are variable —and also as there is always the possibility that new data items, such as ICCIDs, may be added in the future— please make sure to read in the header row and record rows together. For example, if you implement a program that reads in the CSV using fixed definitions, with the first data item set as “imsi” and the second data item set as “date,” when you use SORACOM Canal/Direct, the “vpgId” data item would be output to the CSV, or the ICCID may be output sometime in the future as an additional data item. This means that your program will no longer be able to read the data in correctly. Hence, please process the CSV data first before using it, by converting the records into key/value pairs, using objects, hash tables, associative arrays, etc.

Importing to Excel

If you are using Office 2013 or another old version of Excel, due to encoding issues, text in Japanese and other similar languages may not be displayed correctly when opening the CSV file. In this case, follow the steps below to import the CSV file into Excel.

From the download folder or similar, open the downloaded CSV file using a text editor that supports UTF-8.

Select the text in the text editor and copy it.

open text wi

Run Excel and open up a new worksheet.

Select the first cell in the worksheet (A1) and paste the text.

Excel paste

Use the Text Wizard.

Use the Text Wizard

Select “Delimited” and click on “Next.”

Use the Text Wizard

Select comma as a delimiter, untick “Treat consecutive delimiters as one,” and click on “Next.”

Use the Text Wizard

Set the data format to “General” and click on “Finish.”

Use the Text Wizard

The steps above will allow you to import data into Excel. If the IMSIs are not displayed as numbers, select the IMSI column and change its format to a number.

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop