Soracom

BILLING_HISTORY

Monthly billing summary records.

Public Contract

  • Rows are limited to the current SORACOM Query request context.

Data Freshness

Updated as billing records are finalized.

Columns

Column Type Description
YEAR_MONTH TEXT Year and month in YYYY-MM format.
OPERATOR_ID TEXT Operator identifier associated with the row.
AMOUNT NUMBER Total charge amount.
CURRENCY TEXT Currency code for the charge.
PAYMENT_ITEM_SUMMARY VARIANT Summary of payment items.
PAYMENT_TRANSACTION_ID TEXT Payment transaction identifiers associated with the billing record.
STATE TEXT Current billing record state.

JSON / VARIANT Fields

PAYMENT_ITEM_SUMMARY contains billing item details as JSON. The shape commonly includes:

{
  "billName": "monthlyPayment-202006",
  "categorizedItems": {
    "<itemKey>": {
      "amount": -456.4485,
      "category": "<itemKey>",
      "quantity": 1,
      "taxFreeAmount": 0,
      "unitPrice": 0
    }
  }
}

categorizedItems is an object keyed by billing item key. Each item key maps to an object with amount, category, quantity, taxFreeAmount, and unitPrice.

Billing item keys may include plan-specific suffixes such as ::plan01s or ::plan-NA1-package. Use LIKE with a wildcard when searching for renewal charges or a charge family.

Some billing item key families may include private qualifiers. In the list below, <PRIVATE_QUALIFIER> means the qualifier is redacted and is not a literal key value. Query those families by stable prefix, for example STARTSWITH(item.key, 'ONE_YEAR_CONTRACT_EXTENSION_CHARGE_FOR_').

Known billing item keys include:

SORACOM_AIR_BASIC_CHARGE
SORACOM_AIR_DATA_CHARGE
SORACOM_AIR_CUSTOM_DNS_CHARGE
SORACOM_AIR_IN_VPG_CUSTOM_DNS_CHARGE
SORACOM_AIR_CHAP_AUTHENTICATION_CHARGE
SORACOM_AIR_IN_VPG_CHAP_AUTHENTICATION_CHARGE
SORACOM_AIR_SMS_CHARGE
SORACOM_AIR_INTERNATIONAL_SMS_CHARGE
SORACOM_AIR_VOICE_CHARGE
SORACOM_AIR_SUBSCRIBER_SUSPENSION_CHARGE
SORACOM_AIR_SUBSCRIBER_ACTIVATION_CHARGE
SORACOM_AIR_SUBSCRIBER_CONTRACT_RENEWAL_CHARGE
SORACOM_AIR_SUBSCRIBER_TERMINATION_CHARGE
SORACOM_AIR_SUBSCRIPTION_CONTRACT_RENEWAL_CHARGE
SORACOM_AIR_SUBSCRIPTION_DELIVERY_CHARGE
SORACOM_AIR_SUBSCRIPTION_USAGE_CHARGE
ACTIVATED_SIM
ONE_YEAR_CONTRACT_EXTENSION_CHARGE_FOR_<PRIVATE_QUALIFIER>
EXTENSION_CONTRACT_FOR_2YEARS_CONTRACT_CHARGE_FOR_<PRIVATE_QUALIFIER>
VPG_SETUP_CHARGE
VPG_CANAL_SETUP_CHARGE
VPG_DIRECT_SETUP_CHARGE
VPG_DOOR_SETUP_CHARGE
VPG_FIXED_GLOBAL_IPADDRESS_OPTION_CHARGE
SORACOM_AIR_VPG_CHARGE
SORACOM_AIR_INSPECTION_CHARGE
SORACOM_AIR_BASIC_CHARGE_FOR_KM1
SORACOM_AIR_TRAFFIC_CHARGE_FOR_KM1
SORACOM_AIR_SUBSCRIBER_ACTIVATION_CHARGE_FOR_KM1
SORACOM_AIR_CONTRACT_RENEWAL_CHARGE_FOR_KM1
SORACOM_AIR_READY_STATUS_CHARGE_FOR_PLAN_D_WITH_BUNDLE
SORACOM_AIR_SUSPENDED_STATUS_CHARGE_FOR_PLAN_D_WITH_BUNDLE
SORACOM_AIR_BUNDLE_CHARGE_FOR_PLAN_D_WITH_BUNDLE
SORACOM_AIR_ADDITIONAL_DATA_CAPACITY_CHARGE_FOR_PLAN_D_WITH_BUNDLE
SORACOM_AIR_READY_STATUS_CHARGE_FOR_PLAN_K2_WITH_BUNDLE
SORACOM_AIR_SUSPENDED_STATUS_CHARGE_FOR_PLAN_K2_WITH_BUNDLE
SORACOM_AIR_BUNDLE_CHARGE_FOR_PLAN_K2_WITH_BUNDLE
SORACOM_AIR_ADDITIONAL_DATA_CAPACITY_CHARGE_FOR_PLAN_K2_WITH_BUNDLE
SORACOM_AIR_READY_STATUS_CHARGE_FOR_PLAN_DU
SORACOM_AIR_BUNDLE_CHARGE_FOR_PLAN_DU
SORACOM_AIR_ADDITIONAL_DATA_CAPACITY_CHARGE_FOR_PLAN_DU
SORACOM_AIR_BUNDLE_CHARGE_FOR_PLAN_NA1_PACKAGE
SORACOM_AIR_EXCESS_DATA_TAFFIC_CHARGE_FOR_PLAN_NA1_PACKAGE
SORACOM_AIR_BUNDLE_CHARGE_FOR_PLAN_X3
SORACOM_AIR_BUNDLE_CHARGE_FOR_PLAN_X3_EU
SORACOM_AIR_EXCESS_DATA_TRAFFIC_CHARGE_FOR_PLAN_X3_EU
SORACOM_AIR_FIXED_RATE_PLAN_INITIAL_CHARGE
SORACOM_AIR_FIXED_RATE_PLAN_TOP_UP_CHARGE
SORACOM_AIR_BASIC_MONTHLY_CHARGE_FOR_DATA_BUNDLE
SORACOM_AIR_OUT_OF_POOL_DATA_CHARGE_FOR_DATA_BUNDLE
SORACOM_AIR_ESIM_PROFILE_INITIAL_CHARGE
SORACOM_BEAM_REQUEST_CHAGE
SORACOM_BEAM_IN_VPG_REQUEST_CHAGE
SORACOM_CANAL_VPG_CHARGE
SORACOM_CANAL_PEERING_CHARE
SORACOM_DIRECT_VPG_CHARGE
SORACOM_DIRECT_VIF_CHARGE
SORACOM_DOOR_VPG_CHARGE
SORACOM_DOOR_VPNCONNECTION_CHARGE
VPG_TYPE_E_CHARGE
VPG_TYPE_E_SETUP_CHARGE
VPG_TYPE_F_CHARGE
VPG_TYPE_F_SETUP_CHARGE
VPG_TYPE_F2_CHARGE
VPG_TYPE_F2_SETUP_CHARGE
VPG_TYPE_X_CHARGE
VPG_TYPE_X_SUPPORT_CHARGE
VPG_TRANSIT_GATEWAY_ATTACHMENT_CHARGE
VPG_TRANSIT_GATEWAY_VPC_ATTACHMENT_CHARGE
VPG_TRANSIT_GATEWAY_PEERING_CONNECTION_CHARGE
SORACOM_ENDORSE_CHARGE
SORACOM_FUNNEL_REQUEST_CHARGE
SORACOM_FUNNEL_IN_VPG_REQUEST_CHARGE
SORACOM_FUNK_REQUEST_CHARGE
SORACOM_FUNK_IN_VPG_REQUEST_CHARGE
SORACOM_HARVEST_CHARGE
SORACOM_HARVEST_FILES_STORE_CHARGE
SORACOM_HARVEST_FILES_EXPORT_CHARGE
SORACOM_INVENTORY_MONTHLY_CHARGE
SORACOM_INVENTORY_EVENT_CHARGE
SORACOM_INVENTORY_DEVICE_REGISTRATION_CHARGE
SORACOM_JUNCTION_CHARGE
SORACOM_JUNCTION_INSPECTION_CHARGE
SORACOM_KRYPTON_PROVISIONING_CHARGE
SORACOM_LAGOON_MONTHLY_CHARGE
SORACOM_LAGOON_LICENSE_PACK_CHARGE
SORACOM_SMS_DELIVERY_CHARGE
SORACOM_SMS_SUBMIT_CHARGE
USSD_REQUEST_CHARGE
PLAN_KM1_LOCATION_OPTION_CHARGE
PLAN_KM1_LOCATION_OPTION_REQUEST_CHARGE
DATA_MONTHLY_CHARGE
DATA_REQUEST_CHARGE
DEVICE_MANAGEMENT_MONTHLY_CHARGE
LORA_GATEWAY_SHARED_SERVICE_MODEL_MONTHLY_CHARGE
LORA_GATEWAY_OWNED_MODEL_FIRST_UNIT_MONTHLY_CHARGE
LORA_GATEWAY_OWNED_MODEL_ADDITIONAL_UNIT_MONTHLY_CHARGE
SIGFOX_MESSAGE_CHARGE
SIGFOX_DEVICE_REGISTRATION_CHARGE
SIGFOX_ANNUAL_CONNECTIVITY_CHARGE
SORACOM_LTE_M_BUTTON_POWERED_BY_AWS_RENEWAL_CHARGE
SORACOM_HARVEST_TERM_EXTENSION_CHARGE
SORACOM_HARVEST_DATA_EXPORT_CHARGE
SORACOM_NAPTER_CHARGE
SORACOM_NAPTER_AUDIT_LOG_CHARGE
SORACOM_NAPTER_AUDIT_LOG_EXPORT_CHARGE
SORACOM_MOSAIC_MONTHLY_CHARGE
AI_ALGORITHM_USAGE_CHARGE
SORACOM_ORBIT_CHARGE
SORACOM_ORBIT_REQUEST_CHARGE
SORACOM_PEEK_CHARGE
SORACOM_PEEK_DATA_STORE_CHARGE
SORACOM_PEEK_DATA_EXPORT_CHARGE
SORACOM_ARC_VIRTUAL_SIM_INITIAL_CHARGE
SORACOM_ARC_VIRTUAL_SIM_WITH_SIM_MONTHLY_CHARGE
SORACOM_ARC_VIRTUAL_SIM_WITHOUT_SIM_MONTHLY_CHARGE
SORACOM_ARC_VIRTUAL_SIM_DATA_TRAFFIC_CHARGE
API_AUDIT_LOG_CHARGE
API_AUDIT_LOG_ENTERPRISE_OPTION_CHARGE
API_AUDIT_LOG_EXPORT_CHARGE
SIGFOX_CONNECTIVITY_CHARGE
SORACOM_PLATFORM_USAGE_CHARGE
SORACOM_PLATFORM_CONNECTION_POINT_USAGE_CHARGE
MINIMUM_REVENUE_OBLIGATION
VCONNEC_BANDWIDTH_WHOLESALE_CHARGE
MANAGED_VCONNEC_CHARGE
ALADIN_USAGE_CHARGE
CONTRACT_FEE
SUBSCRIBER_CONTRACT_FEE
INITIAL_FEE
MINIMUM_MONTHLY_SERVICE_CHARGE
KDDI_GCP_BASIC_CHARGE
KDDI_GCP_DATA_CHARGE_FOR_10MB_INCLUDED_PLAN
KDDI_GCP_EXCEEDED_DATA_CHARGE_FOR_10MB_INCLUDED_PLAN
SORACOM_NAPTER_FOR_KDDI_GCP_CHARGE
S4_USAGE_CHARGE
SURPLUS_SMART_NOTIFICATION_CHARGE
SORACAM_LICENSE_CHARGE
SORACAM_CELLULAR_PACK_MONTHLY_CHARGE
SORACAM_DATA_EXPORT_CHARGE
SORACAM_DEVICE_ATOM_CAM_UNLIMITED_LIVE_STREAM_CHARGE
SORACAM_DEVICE_STATUS_NOTIFICATION_CHARGE
SORACAM_DEVICE_EVENT_NOTIFICATION_CHARGE
SMS_A2P_MESSAGING_CHARGE
SORACOM_CLOUD_MFA_CHARGE
SORACOM_FLUX_BASIC_MONTHLY_CHARGE
SORACOM_FLUX_EVENT_CHARGE
SORACOM_FLUX_CREDIT_CHARGE
FREETIER_SORACOM_AIR_DATA_TRAFFIC
FREETIER_SORACOM_BEAM_REQUEST
FREETIER_SORACOM_ENDORSE
FREETIER_SORACOM_FUNNEL_REQUEST
FREETIER_SORACOM_FUNK_REQUEST
FREETIER_SORACOM_NAPTER
FREETIER_SORACOM_HARVEST
FREETIER_SORACOM_INVENTORY
FREETIER_SORACOM_ORBIT
FREETIER_SORACOM_ORBIT_REQUEST
FREETIER_SORACOM_PEEK_FOR_SIM
FREETIER_SORACOM_ARC_VIRTUAL_SIM_INITIAL_CHARGE
FREETIER_SORACOM_ARC_VIRTUAL_SIM_WITH_SIM_MONTHLY_CHARGE
FREETIER_SORACOM_ARC_VIRTUAL_SIM_WITHOUT_SIM_MONTHLY_CHARGE
SORACOM_COUPON
PREPAID_AMOUNT_USAGE
UNUSED_BUNDLE_AMOUNT_ADJUSTMENT_FEE
CARRIED_OVER_ADJUSTMENT_AMOUNT
INSUFFICIENT_PREPAID_BALANCE_AMOUNT
DISCOUNT_SORACOM_SERVICES_BY_LORA_GATEWAYS
DISCOUNT_SORACOM_SERVICES_BY_SIGFOX_DEVICES
DISCOUNT_SORACOM_SERVICES_BY_PLAN_DU
DISCOUNT_SORACOM_SORACOM_AIR_PLAN_DU_FREE_READY_STATUS
DISCOUNT_SORACOM_AIR_PLAN_D_FREE_READY_STATUS
DISCOUNT_SORACOM_AIR_PLAN_D_WITH_BUNDLE_FREE_READY_STATUS
DISCOUNT_SORACOM_AIR_PLAN_K2_WITH_BUNDLE_FREE_READY_STATUS
DISCOUNT_SORACOM_AIR_PLAN_X3_EU_FREE_BUNDLE_CHARGE
DISCOUNT_SORACOM_AIR_FREE_READY_STATUS
DISCOUNT_IN_VPG_SORACOM_SERVICE
DISCOUNT_IN_VPG_SORACOM_SERVICE_FOR_NON_TAXABLE_CHARGE
DISCOUNT_SORACOM_MOSAIC_FREE_MONTHLY_CHARGE
VOLUME_DISCOUNT_SORACOM_AIR_BASIC_CHARGE
VOLUME_DISCOUNT_SORACOM_AIR_MONTHLY_FIXED_BASIC_CHARGE
TIERED_VOLUME_DISCOUNT_SORACOM_AIR_BASIC_CHARGE
TIERED_VOLUME_DISCOUNT_SORACOM_AIR_BASIC_MONTHLY_CHARGE
TIERED_VOLUME_DISCOUNT_SORACOM_AIR_BASIC_CHARGE_FOR_KM1
TIERED_VOLUME_DISCOUNT_SORACOM_AIR_DATA_CHARGE
DISCOUNT_SORACOM_AIR_DATA_CHARGE
TIERED_VOLUME_DISCOUNT_SORACOM_INVENTORY_MONTHLY_CHARGE
DISCOUNT_FOR_SORACOM_AIR_DATA_CHARGE_BUNDLED_WITH_BASIC_CHARGE
DISCOUNT_FOR_SORACOM_AIR_DATA_CHARGE_INCLUDED_IN_ACTIVATED_SIM
DISCOUNT_FOR_SORACOM_AIR_BASIC_MONTHLY_CHARGE_FOR_PLAN01S_DATA_BUNDLE_PREPAYMENT
DISCOUNT_SORACOM_SMS_SUBMIT_CHARGE
DISCOUNT_SORACOM_SMS_DELIVERY_CHARGE

The known legacy spellings SORACOM_AIR_EXCESS_DATA_TAFFIC_CHARGE_FOR_PLAN_NA1_PACKAGE, SORACOM_BEAM_REQUEST_CHAGE, SORACOM_BEAM_IN_VPG_REQUEST_CHAGE, and SORACOM_CANAL_PEERING_CHARE are preserved here because they may appear in billing item data.

Common Queries

Monthly billing totals:

SELECT
  YEAR_MONTH,
  CURRENCY,
  SUM(AMOUNT) AS total_amount
FROM BILLING_HISTORY
WHERE STATE = 'closed'
GROUP BY YEAR_MONTH, CURRENCY
ORDER BY YEAR_MONTH;

Find renewal-related billing items across plan-specific keys:

SELECT
  YEAR_MONTH,
  CURRENCY,
  item.key AS billing_item_key,
  item.value:amount::FLOAT AS charge_amount
FROM BILLING_HISTORY,
  LATERAL FLATTEN(input => PAYMENT_ITEM_SUMMARY:categorizedItems) AS item
WHERE STATE = 'closed'
  AND item.key LIKE '%RENEWAL_CHARGE%'
ORDER BY YEAR_MONTH;

Use the wildcard match because renewal-related keys can be suffixed by plan, for example SORACOM_AIR_SUBSCRIBER_CONTRACT_RENEWAL_CHARGE::plan01s or SORACOM_AIR_SUBSCRIBER_CONTRACT_RENEWAL_CHARGE::plan-NA1-package.