Metering & usage

ZeroClick bills buyers based on the usage you report. There are two ways to report it: synchronously on each proxied response, or asynchronously in batches. There is one contract for signaling that a buyer's meter is exhausted.

Check before you act#

Before performing a paid action for a ZeroClick buyer, confirm the action is still covered by their plan. If it isn't, don't perform the action. Return the 402 exhaustion response instead, so the agent knows to extend the plan and retry.

ZeroClick does not block requests at the proxy. Your API is the enforcement point: you are the only party that knows the cost of an action before running it, so the exhausted response always comes from you. When a spend cap is reached, ZeroClick notifies you and the buyer, and your API stops serving paid actions until the plan is extended.

Reporting usage#

HTTP/1.1 200 OK
Content-Type: application/json
X-ZeroClick-Usage: api-requests=1, compute-seconds=4
 
{ "result": "..." }

You can combine both: report request-shaped usage with headers and report job-shaped usage in batches. The same meter must only be reported through one channel per action, or it will be counted twice.

When a meter is exhausted#

When a buyer's plan can't cover an action, respond with 402 Payment Required and a reason header:

HTTP/1.1 402 Payment Required
X-ZeroClick-Reason: usage_exhausted

When the agent receives a 402 with one of these reasons, ZeroClick directs it to extend the plan:

After a successful extension the agent retries the original request, so make sure a 402 response has no side effects. The action should be safely repeatable once the plan is topped up.