POST /api/private/v1/usage

修改任意客户某个计量功能的使用量。

鉴权

Authorization: Bearer <PRIVATE_API_KEY>
Content-Type: application/json
Idempotency-Key: usage_20260321_001

Idempotency-Key 为可选请求头，建议在写操作中始终传入，用于幂等控制。

请求体

{
  "customer": "customer_001",
  "feature": "image-generate",
  "action": "deduct",
  "amount": 2
}

字段	类型	必填	说明
customer	string	是	客户用户名
feature	string	是	功能标识（slug）
action	string	是	deduct、add、set_used、set_remaining
amount	number	是	非负整数

成功响应

{
  "ok": true,
  "requestId": "req_123",
  "data": {
    "operation": "deduct",
    "requested": 2,
    "applied": 2,
    "idempotencyKey": "usage_20260321_001",
    "state": {},
    "changes": [
      {
        "subscriptionId": 10,
        "oldUsed": 3,
        "newUsed": 5,
        "remaining": 5
      }
    ]
  }
}

state 字段的结构与授权检查接口中的单项授权快照一致。

可能错误

• 404 CUSTOMER_NOT_FOUND
• 404 FEATURE_NOT_FOUND
• 404 NO_ACTIVE_ENTITLEMENT
• 409 INSUFFICIENT_QUOTA
• 409 IDEMPOTENCY_CONFLICT
• 400 FEATURE_NOT_METERED