Billing Information

Overview

Soracom platform services are post-paid. 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 two methods for viewing your account charges:


Monthly 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.

    https://console.soracom.io

    Billing

  2. Click the Invoices tab.

    https://console.soracom.io

    Monthly Invoices

  3. Click Download Invoice for the month you want to view.

PDF invoices are available only for months where the total monthly account charges have been finalized, and are not available for ongoing billing periods. A billing period begins on the first day of each month at 00:00:00 UTC, and ends on the last day of the same month at 23:59:59 UTC.

If you would like to find detailed information of your account usage for the current month, you can download the Detailed Billing CSV following the instructions below.


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.

  2. Click the Bills tab.

    https://console.soracom.io

    Detailed Billing

  3. To download the CSV for the current month, click the Download the latest bill in CSV Format button.

    To download a CSV for a previous month, first click the month within the Billing history list. Then click the Download the above details in CSV format button.

    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:

Detailed Billing CSV

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:

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.

Billing Record Item Name Is billed when... Unit Applicable Region
basicCharge-ready Subscriber status is Ready Days All
basicCharge-active Subscriber status is Active Days All
basicCharge-inactive Subscriber status is Inactive Days All
basicCharge-suspended Subscriber status is Suspended or Standby Days All
basicMonthlyChargeForPlanKM1 plan-KM1 subscriber status is Active or Inactive Months Japan plan-KM1
subscriberSuspensionCharge Subscriber status is set to Suspended Each Japan
subscriberActivationCharge Subscriber status changes from Suspended or Standby to Active or Inactive Each Global
subscriberContractRenewalCharge Subscriber remains in Suspended or Standby status for more than one year Years All
subscriberActivationChargeForPlanKM1 plan-KM1 subscriber is changed from Ready or Suspended status to Active Each Japan plan-KM1
contractRenewalChargeForPlanKM1 plan-KM1 subscriber remains in Suspended status for more than one year Years Japan plan-KM1
dataTrafficCharge-country-plan Data is uploaded or downloaded, categorized by country and subscription plan Bytes Global
dataTrafficRoundedUpCharge-country-plan The corresponding dataTrafficCharge is rounded to the next minimum billing unit Bytes Global
uploadDataCharge-speed-time Data is uploaded from a subscriber, categorized by upload speed class (s1.fast, etc.) and the time of day (daytime or nighttime) Bytes Japan
downloadDataCharge-speed-time Data is downloaded to a subscriber, categorized by download speed class (s1.fast, etc.) and the time of day (daytime or nighttime) Bytes Japan
dataTrafficChargeForPlanKM1 Data is uploaded or downloaded by a plan-KM1 subscribers Bytes Japan plan-KM1
docomoSMSCharge Domestic SMS is sent to/from a subscriber Each Japan plan-D
docomoInternatinalSMSCharge International SMS is sent to/from a subscriber Each Japan plan-D
kddiSMSCharge-date Domestic SMS is sent to/from a subscriber Each Japan plan-K
kddiInternatinalSMSCharge-date International SMS is sent to/from a subscriber Each Japan plan-K
soracomSmsDeliveryCharge SMS is sent to a subscriber Each Global
soracomSmsSubmitCharge SMS is sent from a subscriber Each Global
ussdRequestCharge USSD request is sent from a subscriber Each Global
customDNSCharge Custom DNS option is enabled Days, per subscriber All
chapAuthenticationCharge CHAP Authentication option is enabled Days, per subscriber All
virtualPrivateGatewayCharge VPG option is enabled Days, per subscriber All
sigfoxDeviceRegistrationCharge Sigfox device is registered Each All
sigfoxAnnualConnectivityCharge Sigfox device registration is renewed Years, per device All
sigfoxMessageCharge-contract-country Device sends message (exceeding allowance) Requests All
loRaGatewayOwnedModelFirstUnitMonthlyCharge First LoRa gateway is registered to an account Months Japan
loRaGatewayOwnedModelAdditionalUnitMonthlyCharge Additional LoRa gateways are registered to an account Months, per gateway Japan
loRaGatewaySharedServiceModelMonthlyCharge Shared LoRa gateways are registered to an account Months, per gateway Japan
soracomBeamRequestCharge-protocol Device sends Beam request, categorized by in/out protocol Requests All
soracomFunnelRequestCharge-protocol Device sends Funnel request, categorized by in/out protocol Requests All
soracomFunkRequestCharge-protocol Device sends Funk request, categorized by in/out protocol Requests All
soracomHarvestCharge Harvest is enabled Days, per device All
soracomHarvestRequestCharge Device sends Harvest request (exceeding allowance) Requests All
soracomHarvestTermExtensionCharge Harvest Extended Retention option is enabled Months All
soracomHarvestDataExportCharge Harvest data is exported (exceeding allowance) Each, per 1GB All
soracomLagoonMonthlyCharge-plan Lagoon is enabled Months All
soracomLagoonLicensePackCharge-license Lagoon license pack is added, categorized by license pack Packs All
soracomEndorseCharge Endorse is enabled Days, per subscriber All
soracomKryptonInitialProvisioningCharge Krypton is enabled and subscriber is provisioned (first month) Months, per subscriber All
soracomKryptonMonthlyProvisioningCharge Krypton is enabled and subscriber is provisioned Months, per subscriber All
soracomInventoryDeviceRegistrationCharge Device is registered to Inventory Each All
soracomInventoryMonthlyCharge Device has one or more management events Months, per device All
virtualPrivateGatewaySetupCharge VPG is created (before May 2016) Each Japan
virtualPrivateGatewayCanalSetupCharge VPG for Canal is created Each All
virtualPrivateGatewayDirectSetupCharge VPG for Direct is created Each All
virtualPrivateGatewayDoorSetupCharge VPG for Door is created Each All
soracomCanalVirtualPrivateGatewayCharge VPG for Canal is running Hour All
soracomDirectVirtualPrivateGatewayCharge VPG for Direct is running Hour All
soracomDoorVirtualPrivateGatewayCharge VPG for Door is running Hour All
soracomCanalVPCPeeringCharge VPG has a VPC Peering Connection Hours, per connection All
soracomDirectVirtualInterfaceCharge VPG has a Virtual Interface Hours, per interface All
soracomDoorVPNConnectionCharge VPG has a VPN connection Hours, per connection All
virtualPrivateGatewayFixedGlobalIpAddressOptionCharge VPG Fixed Global IP Address option is enabled Hours All
soracomJunctionCharge VPG Junction option is enabled Hours All
soracomJunctionInspectionCharge VPG Junction Inspection option is enabled Hours All
soracomNapterCharge Napter on-demand remote access is enabled once or more Months, per subscriber All
soracomNapterAuditLogCharge Napter audit log is enabled Months All
soracomNapterAuditLogExportCharge Napter audit log is exported (exceeding allowance) Each, per 1GB All

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

Discount Record Item Name Is applied when... Unit Region
dataTrafficFreeTier Device includes free data allowance Bytes All
soracomBeamRequestFreeTier Device includes free Beam request allowance Requests All
soracomFunnelRequestFreeTier Device includes free Funnel request allowance Requests All
soracomEndorseFreeTier Device includes free Endorse request allowance Requests All
soracomAirBasicChargeVolumeDiscount Long Term Discount is approved for account Subscribers Japan
soracomAirDataChargeTieredVolumeDiscount Data usage meets tiered volume discount requirement Bytes Global
soracomAirBasicChargeTieredVolumeDiscount Active/Inactive subscribers meets tiered volume discount requirement Subscribers Global
dataTrafficCoupon Coupon for data usage is available in account Amount All
soracomBeamRequestCoupon Coupon for Beam usage is available in account Amount All
soracomEndorseCoupon Coupon for Endorse usage is available in account Amount All
soracomFunnelRequestCoupon Coupon for Funnel usage is available in account Amount All
chargeCoupon Coupon for any Soracom fees is available in account Amount All

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 configuraiton:

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.

Soracom API

You can download the current month's most recent billing information using the exportLatestBilling API:

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

Similarly, you can use the exportBilling API to download the corresponding data for a particular month, instead specifying the YYYYMM in the query path:

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

While each monthly billing period ends on the last day of the given month at 23:59:59 UTC, the CSV may not be immediately available download via the exportBilling API using the YYYYMM query path format. Billing calculations for the most recent completed month are generally completed within 1 to 3 business days from the start of the proceeding month.

Notes on Parsing CSV Data

All CSV data is encoded in UTF-8 (with BOM). Ensure that you parse the data accordingly.

  • If a value contains any commas ,, the entire value will be enclosed within double-quotes ".
  • If a value contains any double-quote ", each double-quote will be escaped using two double-quotes "".

Ensure that your CSV parser is configured to correctly parse according to these rules.

In general, as the data columns are variable and may be subject to additional fields in the future, there is a possibility that a particular column may not be in the same position when parsing different CSV files. When implementing a CSV parser, ensure that you either process the first row in order to confirm the column order, or restructure the data into key/value pairs, objects, hash tables, or associative arrays using an adequate CSV parser.