Account Management

Billing Information

Overview

Soracom platform services are postpaid. All data usage charges, connection fees (such as Custom DNS), network services (VPG, Canal, etc.), and application services (Beam, Funnel, Funk, Harvest, etc.) within a given month are aggregated at the end of each month.

Soracom provides a Billing Alert function that allows you to receive a notification if your current monthly bill exceeds a specific amount. By configuring an alert, you can be notified of unexpected charges that may occur due to unexpected data usage or other billable services, and proactively take control.

Soracom also provides two methods for viewing your account charges:

• Monthly Invoices - A PDF report summarizing your total account charges, broken down by each Soracom service or option.
• Detailed Billing CSV - A CSV file containing the full list of account charges, broken down by each day in a given month, and further categorized by device, service, or option.

Billing Dashboard

You can see an overview of your usage charges for the last four months, including the current month, from the User Console.

To access the Billing Dashboard:

1. Login to the User Console. Click your account menu, then select Billing Dashboard.

   https://console.soracom.io

   

2. Click Billing Dashboard

   The following panels are displayed:

Billing Alerts

By default, Soracom will regularly update your current month's bill total so that you can easily check your service usage as service charges accrue. When the Billing Alert function is enabled, Soracom will also check if the monthly bill total exceeds a threshold that you set, and if so, send an email notification to the root account email address.

The Billing Alert function only sends an email notification when triggered and does not make any changes to your SIMs or any configured services. Your Soracom services will continue to operate normally without interruption.

To set up a billing alert:

1. Login to the User Console. Click your account menu, then select Billing Dashboard.

   https://console.soracom.io

   

   Because billing is processed separately for Global and Japan coverage types, Billing Alerts must also be configured separately. If you are using both coverage types, make sure to set up a Billing Alert for each coverage.

2. Click Notifications & Alerts.

   https://console.soracom.io

   

3. Click Enable Alert, then configure the following items:

   • Threshold (required) - The bill amount that will trigger an alert notification. When your monthly bill exceeds this amount, a notification will be sent to the root account email address.

   • Edit email subject/body (optional) - The alert notification sent to your root account email address will provide basic information by default. If you want to customize the email subject or body (such as to match specific filters in your email service provider), check this box to modify the email.

     The following placeholder variables can also be used inside the email subject and body. If a billing alert is sent, the variables will be replaced by their corresponding actual values.

     • ${operatorId} - The Operator ID of the account. This may be useful if you have multiple Soracom accounts and want to know from which account the Billing Alert occurred.
     • ${coverage} - The coverage type from which coverage the Billing Alert occurred. This will be replaced with g for Global Coverage or jp for Japan Coverage.
     • ${limitTotalAmount} - The threshold value specified above.
     • ${currentTotalAmount} - The actual current monthly bill amount, at the time the Billing Alert was triggered.
4. Click Save.

Monthly Invoices

Downloading Invoices

Monthly invoices containing the summary of your account charges are prepared at the end of each month and available for download from the User Console.

To download a past invoice:

1. Login to the User Console. Click your account menu, then select Billing Dashboard.

   https://console.soracom.io

   

2. Click the Billing & Payment History tab.

   https://console.soracom.io

   

3. Click the button next to the month you want to view and select Download Invoice. This is available as a PDF.

Receiving Invoices by Email

When a monthly invoice has been finalized, an email notification will be sent to notify you that the invoice is ready for download from the User Console. You can additionally opt in to receive the invoice directly via email. When this option is enabled, the PDF invoice will be attached directly to the email notification.

To enable receiving monthly invoices via email:

1. Login to the User Console. Click your account menu, then select Email settings.

   https://console.soracom.io

   

2. In the Email Addresses section, add an email address under the Billing option.

   https://console.soracom.io

   

3. To enable receiving invoices directly by email, check the Send a PDF copy of my invoice to my email checkbox in the Configuration section at the bottom of the page.

   

Detailed Billing CSV

For the full itemized list of charges incurred on your Soracom account, you can download a CSV file which contains the full breakdown of all usage, service, and option charges.

Detailed billing CSV files are available for each past month of usage, as well as for the current month.

Downloading a CSV

1. Login to the User Console. Click your account menu, then select Billing Dashboard.

2. Click the Billing & Payment History tab.

3. To download the CSV for the current month, click the Download service usage charges button button at the top of the page

   https://console.soracom.io

   

4. To download a CSV for a previous month, locate the invoice within the Billing & Payment History list. Then click the button to the right and select Download service usages charges

   https://console.soracom.io

   

   Each CSV file may take a minute to generate, depending on the number of devices, services, or options active during the given month.

CSV files for the current month are updated once per day.

Understanding the CSV format

The detailed billing CSV file provides a complete breakdown of every device, service, or option charge incurred in your Soracom account for a given month.

Once you have downloaded a detailed billing CSV file, you can open it with a suitable spreadsheet application. The data should look something like this:

• First Row - Header information. These items help identify or classify the content below. This section is broadly separated into the following:
  • Amount Data Items - Data that corresponds to a specific billable item (Includes IMSI, VPGID, Date, etc.).
  • Supplemental Information Items - Additional data used to help identify the corresponding billable item, including any device or group name associated with the item (Includes Tag, Group Name, etc.).
• Second Row Onward - Data record rows. These rows contain the actual billing information for the given month. This section is broadly separated into the following:
  • Billing Records - Billable device, service, or option charges.
  • Discount Records - Discounts applicable to the billable records, including free tier allowances, volume discounts, and coupons.

Billing Record Breakdown

A billing records is created for each subscriber or VPG in your account, for each day and for each billing data item. For example, if you have 1 active SIM card in your account which has consumed data during the given month, you will see at a minimum the following billing records:

• basicCharge - The daily basic fee for the SIM card, for a specific day in the given month.
• dataTrafficCharge - The data usage charge for the SIM card, for a specific day in the given month.

Any additional options, such as Custom DNS, sending or receiving SMS, and application services such as Harvest, will also be listed as separate billing records.

Each billing record line will contain either the IMSI or VPG ID which the billing record corresponds to, the raw unit price, quantity, and billing record amount. The units used for each billing record vary depending on the billing record type, and therefore are omitted from the CSV data. Information on the units used for each record type are listed in the table below.

Billing records are calculated for each day, beginning at 00:00:00 UTC and ending at 23:59:59 UTC. The dates listed in the CSV data are written using YYYYMMDD format. For certain discounts which apply to any usage within a given month, the date will be indicated using YYYYMM format instead.

These rules also apply to other device types, as well as to billable platform services such as Virtual Private Gateways.

Discount records also follow the same rules, with the amount represented as a negative number in order to indicate reduction of cost.

Taxable amounts are not included in the CSV data. In order to calculate any applicable taxes, simply add all of the values in the amount column to determine the billing total, then apply any taxation rules as needed using this total amount.

CSV Item Name Reference

The following items appear when your account is billed for a particular device, service, or option.

The following items appear when an allowance, discount, or coupon is applicable to one or more of the billable items:

Tags and Groups

The Tag/Group Data Items section includes the tags and group names configured for each SIM. For example, if a SIM in your account has the following configuration:

• Name - MySIM
• Tags
  • MyCustomTag1 - MyCustomValue1
  • MyCustomTag2 - MyCustomValue2
• Group - abcdef00-0000-0000-0000-000012345678 (MyGroup)

The following data will be appended to the CSV header (first line), as well as to any line items for the SIM:

name,MyCustomTag1,MyCustomTag2,group:groupId,group:name
MySIM,MyCustomValue1,MyCustomValue2,abcdef00-0000-0000-0000-000012345678,MyGroup

You can use tags to quickly group or filter the CSV to make calculations based on custom tag value or group name.

Programmatic Usage

You can also access the detailed billing information programmatically in order to integrate information on Soracom platform usage within your application.

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://g.api.soracom.io/v1/bills/latest/export

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://jp.api.soracom.io/v1/bills/latest/export

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://g.api.soracom.io/v1/bills/201901/export

curl -X POST \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://jp.api.soracom.io/v1/bills/201901/export