ConverterHQ separates commercial accounting from conversion execution. The public API exposes enough information to estimate work and reconcile usage without requiring clients to implement their own billing ledger.
Estimate before execution
Use POST /v1/estimates when your product needs a pre-flight cost or resource estimate. Estimates use the known conversion pair and supplied hints; the final charge can differ when the actual input characteristics or execution path differ.
The monthly allowance counts one admitted production Job containing a conversion, including REST, workflows, signed links and MCP. Polling, uploads and sandbox Jobs do not consume this allowance. Replaying a submission with the same Idempotency-Key consumes it once. An exhausted allowance returns QUOTA_EXCEEDED before work starts. Failed or cancelled admitted Jobs still count; credit release follows the separate execution policy. Read the account counter through GET /v1/commercial.
Reservation and settlement
Paid work can reserve commercial capacity before execution and settle against the authoritative result afterward. A reservation is not a second charge. Cancellation and terminal failure follow the plan's documented settlement policy, and abandoned reservations are reconciled rather than left indefinitely pending.
Retries and duplicate delivery
Infrastructure redelivery, worker retries and client-requested retries must not create accidental duplicate charges for the same logical attempt. Use idempotency keys when creating work and retain Job/Task identifiers when reconciling invoices or usage exports.
Usage and reconciliation
GET /v1/usage and GET /v1/usage/summary are the account-facing source for metered activity. Store your own client_reference_id when you need to map ConverterHQ usage back to an order, tenant or internal workflow.
Sandbox and production
Test credentials operate in an isolated sandbox and do not consume production credits. Live credentials address production resources and billing. Never use environment detection based only on hostname inside business logic; let the credential/environment configuration select the correct API base.