Account Management
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 - 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 broken down for each Soracom device, service, or option.
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:
-
Login to the User Console. Click your account menu, then select Billing.
-
Click the Invoices tab.
- 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
-
Login to the User Console. Click your account menu, then select Billing.
-
Click the Bills tab.
-
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:
- 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.
- Tag/Group Data Items - Additional data used to help identify the corresponding billable item, including any device or group name associated with the item.
- 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.
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 |
basicMonthlyCharge-plan | Subscriber with monthly plan is Active or Inactive | Months | All |
subscriberActivationCharge | Subscriber status changes from Suspended or Standby to Active or Inactive | Each | Global |
subscriberSuspensionCharge | Subscriber status is set to Suspended | Each | Japan |
subscriberContractRenewalCharge | Subscriber remains in Suspended or Standby status for more than one year | Years | All |
subscriptionDeliveryCharge-plan | planP1 or planX1 subscription container is added to a subscriber | Each | Global |
subscriptionUsageCharge-plan | planP1 or planX1 subscription container is Active | Months | Global |
subscriptionContractRenewalCharge-plan | planP1 or planX1 subscription container is renewed | Years | Global |
basicMonthlyChargeForPlanKM1 | plan-KM1 subscriber status is Active or Inactive | Months | Japan plan-KM1 |
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 |
planKM1LocationOptionCharge | plan-KM1 subscriber Simple Location Service option is enabled | Months | Japan plan-KM1 |
planKM1LocationOptionRequestCharge | plan-KM1 subscriber Simple Location Service information is requested | Each | Japan plan-KM1 |
readyStatusChargeForPlanDU | plan-DU subscriber status is Ready | Months | Jpaan plan-DU |
bundleChargeForPlanDU-bundle | plan-DU subscriber status is Active or Inactive | Months | Japan plan-DU |
additionalDataCapacityChargeForPlanDU | plan-DU data capacity is added | Each | Japan plan-DU |
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 |
inVPGCustomDNSCharge | Same as above while subscriber is attached to a VPG | Days, per subscriber | All |
chapAuthenticationCharge | CHAP Authentication option is enabled | Days, per subscriber | All |
inVPGChapAuthenticationCharge | Same as above while subscriber is attached to a VPG | 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 |
inVPGSoracomBeamRequestCharge-protocol | Same as above while subscriber is attached to a VPG | Requests | All |
soracomFunnelRequestCharge-protocol | Device sends Funnel request, categorized by in/out protocol | Requests | All |
inVPGSoracomFunnelRequestCharge-protocol | Same as above while subscriber is attached to a VPG | Requests | All |
soracomFunkRequestCharge-protocol | Device sends Funk request, categorized by in/out protocol | Requests | All |
inVPGSoracomFunkRequestCharge-protocol | Same as above while subscriber is attached to a VPG | 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 |
soracomHarvestFilesStoreCharge | Files are uploaded to Harvest Files | Per GB | All |
soracomHarvestFilesExportCharge | Files are downloaded from Harvest Files | Per GB | 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 Type-C (for Canal) is created | Each | All |
virtualPrivateGatewayDirectSetupCharge | VPG Type-D (for Direct) is created | Each | All |
virtualPrivateGatewayDoorSetupCharge | VPG Type-D (for Door) is created | Each | All |
virtualPrivateGatewayTypeESetupCharge | VPG Type-E is created | Each | All |
virtualPrivateGatewayTypeFSetupCharge | VPG Type-F is created | Each | All |
soracomCanalVirtualPrivateGatewayCharge | VPG Type-C (for Canal) is running | Hour | All |
soracomDirectVirtualPrivateGatewayCharge | VPG Type-D (for Direct) is running | Hour | All |
soracomDoorVirtualPrivateGatewayCharge | VPG Type-D (for Door) is running | Hour | All |
virtualPrivateGatewayTypeECharge | VPG Type-E is running | Hour | All |
virtualPrivateGatewayTypeFCharge | VPG Type-F 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 |
soracomOrbitCharge | Orbit is enabled | Months, per subscriber | All |
soracomOrbitRequestCharge | Device sends or receives Orbit request | Requests | All |
soracomPeekChargeForVPG | Peek on-demand packet capture is used once or more | Days, per VPG | All |
soracomPeekDataStoreChargeForVPG | Peek packet capture data is stored (exceeding allowance) | Each, per 1GB | All |
soracomPeekDataExportCharge | Peek packet capture data 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:
- 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.
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.