Quota & Minting

Minting is the operation that grants a Token Plan tier to one of your customers and debits your quota. Because it moves money, the API is idempotent: you can safely retry without ever double-charging your quota. This page explains exactly how that works and how to build a reliable client on top of it.

Every mint carries an operation_id that you generate. It is your idempotency key: a non-empty string of at most 128 characters that identifies a single mint *intent*. zrouter computes the idempotency fingerprint server-side from operation_id, customer_email, and plan_tier_id — you do not send a separate hash.

If you repeat a mint with the same operation_id and the same payload (same email and tier), the API treats it as a replay. It returns 200 with already_applied: true and performs no additional debit — the original grant and the single debit stand unchanged. Retrying a request that was actually applied can therefore never charge you twice.

If you reuse an operation_id with a different payload — for example a different customer_email or plan_tier_id — the request fails with 409 idempotency_conflict. This server-side check makes accidental reuse of a stale id impossible to mistake for a new mint.

• Generate the operation_id once per intent, before any network call. A UUID or a random token works well.
• Disable the submit button while a mint is in flight so a double-click cannot fire two requests with different ids.
• Retry with the same operation_id on transient failures (429, 5xx, timeout). Never generate a fresh id on retry.
• Keep the operation_id until you get a definitive result. If the response is lost, replay the exact same request to learn whether it applied.

A mint is applied as a single atomic unit: the debit of your quota and the Token Plan grant to the customer either both happen, or neither happens. There is no window where your quota has been debited but the customer received nothing, or the customer received a grant your quota did not pay for. Combined with idempotency, this means the worst outcome of any retry storm is one grant and one debit.

The two requests below are the same request. The first applies the mint; the second — for example after a lost response — replays it with the same operation_id and returns already_applied: true without a second debit.

curl -X POST "https://api.zrouter.dev/api/reseller/mint" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "op_1234567890abcdef",
    "customer_email": "[email protected]",
    "plan_tier_id": "<tier-id>"
  }'