Skip to main content
上报自定义计费事件,用于 App 的按次(PER_USE)计费场景。每次事件上报会根据 Meter 配置从授权用户的积分中扣除相应金额。

认证

此端点仅支持 OAuth Bearer Token。API Key 认证会返回 401 错误。自定义计费事件从用户账户扣除积分,必须通过 OAuth 确保用户知情同意。

请求体

string
必填
事件名称,必须与 App 中配置的 Meter 事件名完全匹配。最大 100 个字符。
string
必填
幂等键,用于防止重复扣费。相同的 idempotency_key 不会被重复计费。最大 128 个字符。
object
附加元数据,键值对形式。用于记录额外的业务信息,不影响计费。

请求示例

响应

正常扣费

幂等重放

当同一个 idempotency_key 被重复提交时,不会重复扣费:
idempotent_replay: true 表示这是一次幂等重放,积分未被重复扣除。

幂等性保障

始终使用有意义的幂等键。推荐格式:{业务实体}_{业务ID}_{操作},例如 order_12345_gen_1
  • 防止网络重试导致的重复扣费 — 客户端超时重试时,相同的幂等键保证只扣一次
  • 防止业务逻辑重复调用 — 同一个业务操作多次调用只会扣一次
  • 幂等窗口 — 同一 (app_uuid, idempotency_key) 组合永久有效

工作原理

  1. 你的 App 通过 OAuth 获取用户授权
  2. 用户使用付费功能时,调用 Events API 上报事件
  3. 袋袋根据 App 配置的 Meter 查找对应的积分价格
  4. 从授权用户的积分中扣除对应金额
  5. 返回扣费结果和剩余余额

每日消费上限

平台对 每个 App × 每个终端用户 设置了每日消费上限,默认 500 积分/天app_daily_cap.daily_limit 列默认值,可按用户单独调整)。达到上限时后续事件上报被拒绝,返回 HTTP 429,响应里带 daily_limit 字段。
两个容易踩的细节:
  1. 重置边界是 UTC 零点,不是北京时间零点。判定用的是 new Date().toISOString() 取出的日期串,所以对中国区用户来说,额度在北京时间早上 8 点重置。
  2. 上限是按终端用户隔离的,不是按 App 总量。也就是说单个终端用户刷爆自己的额度不会影响你的其他用户;反过来,你也无法通过”App 总量还有余”来绕过某个用户的上限。

错误码

下一步

计量器配置

查询 App 的 Meter 配置

构建袋袋 App

完整的 App 开发流程