Reconcile an entitlement snapshot

POST

/v1/billing/entitlement-reconciliations

Writes a canonical entitlement reconciliation into the billing contract so callback, worker, and admin follow-on surfaces share the same write-side seam.

请求参数

Body 参数application/json必填

示例

{
    "userID": "local-user-001",
    "plan": "pro",
    "allowedModes": [
        "voiceInput",
        "translation",
        "rewrite"
    ],
    "remainingQuotaSeconds": 7200,
    "remainingAddonSeconds": 600,
    "reason": "Promote a retained paid-order reconciliation into the billing snapshot.",
    "source": "commerce_callback",
    "sourceReference": "tinyship-order-1001",
    "effectiveAt": "2026-04-01T16:30:00Z"
}

请求示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location '/v1/billing/entitlement-reconciliations' \
--header 'Content-Type: application/json' \
--data '{
    "userID": "local-user-001",
    "plan": "pro",
    "allowedModes": [
        "voiceInput",
        "translation",
        "rewrite"
    ],
    "remainingQuotaSeconds": 7200,
    "remainingAddonSeconds": 600,
    "reason": "Promote a retained paid-order reconciliation into the billing snapshot.",
    "source": "commerce_callback",
    "sourceReference": "tinyship-order-1001",
    "effectiveAt": "2026-04-01T16:30:00Z"
}'

返回响应

🟢200成功

application/json

Entitlement reconciliation recorded.

Bodyapplication/json

示例

{
    "endpoint": "POST /v1/billing/entitlement-reconciliations",
    "reconciliation": {
        "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
        "userID": "local-user-001",
        "plan": "pro",
        "allowedModes": [
            "voiceInput",
            "translation",
            "rewrite"
        ],
        "remainingQuotaSeconds": 7200,
        "remainingAddonSeconds": 600,
        "totalRemainingSeconds": 7800,
        "reason": "Promote a retained paid-order reconciliation into the billing snapshot.",
        "source": "commerce_callback",
        "sourceReference": "tinyship-order-1001",
        "reconciledAt": "2026-04-01T16:30:00Z"
    },
    "snapshot": {
        "userID": "local-user-001",
        "plan": "pro",
        "allowedModes": [
            "voiceInput",
            "translation",
            "rewrite"
        ],
        "remainingQuotaSeconds": 7200,
        "remainingAddonSeconds": 600,
        "totalRemainingSeconds": 7800,
        "asOf": "2026-04-01T16:30:00Z"
    }
}

修改于 2026-08-26 04:04:36

Consume quota

Read service health snapshots