BILL_ITEMS

Per-entity billing line item records.

BILL_ITEMS contains billing line items for charged entities such as SIMs, devices, or operator accounts. Each row represents a charge or aggregate billing item for an entity, date, and billing item name.

Use BILLING_MONTH for month-level filtering, and use BILL_ITEM_NAME to group charges by item type.

Public Contract

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

Data Freshness

Updated as billing item records are finalized.

Columns

Column	Type	Description
SIM_ID	TEXT	SIM identifier resolved when the charged entity is a SIM IMSI, when available.
CHARGED_ENTITY	TEXT	Identifier of the entity the charge applies to, such as a SIM IMSI, device ID, operator ID, or other billable entity.
OPERATOR_ID	TEXT	Operator identifier associated with the row.
BILLING_MONTH	TEXT	Billing month in YYYY-MM format.
DATE	DATE	Date associated with the billing item.
BILL_ITEM_NAME	TEXT	Billing item name or charge code.
STATE	TEXT	Billing item state.
AMOUNT	NUMBER	Billing item charge amount.
UNIT_PRICE	NUMBER	Unit price for the billing item when available.
QUANTITY	NUMBER	Quantity of units billed when available.
CURRENCY	TEXT	Currency code for the billing item.
CURRENCY_EXCHANGE	VARIANT	Currency exchange details when available.
TAX_FREE_AMOUNT	NUMBER	Tax-free portion of the billing item amount.
TAX_CLASS	TEXT	Tax classification for the billing item.
DISCOUNT_AMOUNT	NUMBER	Discount amount applied to the billing item when available.
DISCOUNT_DESCRIPTION	TEXT	Description of the discount applied when available.
UPDATE_DATE_TIME	TIMESTAMP_NTZ	When the billing item was last updated.

JSON / VARIANT Fields

CURRENCY_EXCHANGE contains currency exchange details when an exchange value is associated with the billing item. The exact fields can vary by record.

Query optional fields with explicit casts and null checks.

Example:

SELECT
  SIM_ID,
  BILLING_MONTH,
  BILL_ITEM_NAME,
  CURRENCY_EXCHANGE
FROM BILL_ITEMS
WHERE CURRENCY_EXCHANGE IS NOT NULL;

Common Queries

Monthly total by billing item:

SELECT
  BILLING_MONTH,
  BILL_ITEM_NAME,
  CURRENCY,
  SUM(AMOUNT) AS total_amount
FROM BILL_ITEMS
GROUP BY BILLING_MONTH, BILL_ITEM_NAME, CURRENCY
ORDER BY BILLING_MONTH, total_amount DESC;

Charges for a charged entity across billing months:

SELECT
  BILLING_MONTH,
  DATE,
  BILL_ITEM_NAME,
  AMOUNT,
  CURRENCY
FROM BILL_ITEMS
WHERE CHARGED_ENTITY = '440000000000001'
  AND BILLING_MONTH BETWEEN '2025-01' AND '2025-03'
ORDER BY DATE, BILL_ITEM_NAME;

Discounted billing items:

SELECT
  BILLING_MONTH,
  SIM_ID,
  BILL_ITEM_NAME,
  DISCOUNT_AMOUNT,
  DISCOUNT_DESCRIPTION
FROM BILL_ITEMS
WHERE DISCOUNT_AMOUNT IS NOT NULL
ORDER BY BILLING_MONTH, SIM_ID;