GET /apiv2/billing/usage

您的后付费扣费记录：订单中每个单独计费的组件占一行，最新的排在最前。扣费行会在服务提供并记录后显示，可能会晚于订单响应的时间。可用于对账订单、欠款以及发票。属于后付费计费的一部分。

接口 URL

GET https://netts.io/apiv2/billing/usage

请求头

请求头	是否必填	描述
X-API-KEY	是	拥有 billing.read 权限的 API 密钥
X-Real-IP	是	密钥白名单中的地址

查询参数

参数	是否必填	描述
from	否	此刻起的扣费记录，带时区的 ISO 8601 格式：2026-10-01T00:00:00Z
to	否	此刻之前的扣费记录，格式相同
limit	否	每页行数，1–500，默认为 100
cursor	否	上一页返回的 nextCursor

不带时区的时间将被拒绝并返回 400 invalid_request —— 因为时间范围会产生歧义。

示例

curl -s 'https://netts.io/apiv2/billing/usage?from=2026-10-01T00:00:00Z&limit=2' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-Real-IP: 203.0.113.10'

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 1024,
        "orderId": "AB2EF201B582AA1",
        "productCode": "energy_1h",
        "address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "quantity": 65000,
        "unitPriceSun": "20.000000",
        "discount": null,
        "amountTrx": "1.300000",
        "amountUsdc": "0.430096",
        "usdPerTrx": "0.330842760000000000",
        "quoteId": null,
        "txHash": "5c1f0e0d3a2b4c6d8e9f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f",
        "fulfilledAt": "2026-10-19T10:11:42.563494+00:00",
        "status": "accrued",
        "paidTrx": "0.000000",
        "paidUsdc": "0.000000",
        "invoiceId": null,
        "reversesId": null
      }
    ],
    "nextCursor": 1023
  },
  "timestamp": "2026-10-19T20:31:10+00:00"
}

扣费明细

字段	描述
id	扣费编号
orderId	此扣费所属的订单 —— 与订单接口返回的 ID 相同
productCode	energy_1h、energy_5m、bandwidth、activation 或 aml_check
address	订单对应的 TRON 地址
quantity	Energy 或 Bandwidth 数量，激活或检查则为 1
unitPriceSun	向您收取的每单位价格（单位为 SUN），包含您的专属价格；按订单定价的产品为 null
discount	该订单的单独折扣 —— type 为 percent 或 sun_per_unit 及其 value —— 或为 null
amountTrx, amountUsdc	该组件记录的金额，以 TRX 及您的合同货币计
usdPerTrx	为该组件记录的 TRX 对您合同货币的汇率：如果报价锁定了金额则取自报价，否则取自提供服务时的汇率
quoteId	订单使用的报价（如果有）
txHash	该组件的 TRON 交易哈希（如果有）
fulfilledAt	该组件交付的时间，UTC
status	accrued —— 尚未开具发票；invoiced；paid；reversed —— 已被后续更正冲销
paidTrx, paidUsdc	该扣费已支付的金额，以 TRX 及您的合同货币计
invoiceId	包含该扣费的发票
reversesId	针对更正行：其所冲销的扣费记录

包含 Energy 和激活的订单将有两行记录，每个部分各占一行。更正操作绝不会修改旧记录行：而是添加一个带有 reversesId 的新行。

分页

将 nextCursor 的值作为 cursor 发送，以获取下一页（更早的记录）。在最后一页上，nextCursor 为 null。

错误

HTTP	code	含义
400	invalid_request	参数错误，或 from/to 未包含时区
401	-1, -2	密钥缺失或无效，或 IP 不在白名单中 —— 由 API 网关响应，请参见响应格式
403	billing_read_required, postpaid_required	无权限，或未开通后付费计费