Create usage

Debits one act an application metered to the org it acts for, and answers the receipt.

POST /v1/billing/usage

Billing → · All API references → · Get started →


Address	`https://api.hanzo.ai/v1/billing/usage`
Method	`POST`
Operation	`post_billing_usage`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Debits one act an application metered to the org it acts for, and answers the receipt.

The caller is an application acting as itself — an IAM client_credentials token — and the org is the one that token acts in: the application's own, or one that granted it membership, selected with X-Org-Id and named again in org. A person, an API key, an unauthenticated caller, and a body naming an org the token does not act in are all refused before anything is debited.

The debit lands in the same ledger every other meter writes, in the wallet GET /v1/billing/balance reports for the same caller. It is exactly-once on id: a retry answers the same receipt, and the same id for a different amount is 409. Recording does not gate — the work already happened — so a caller that must refuse unfunded work asks GET /v1/billing/balance and GET /v1/billing/alerts/authorize first.

Request

8 fields, body application/json (required).

Field	In	Type	Required	Description
`amount`	body	billing.Money	—
`amount.currency`	body	string	yes
`amount.decimal`	body	string	yes
`id`	body	string	—	ID names the act, chosen by the reporting application and stable across its retries: the ledger debits one act once.
`model`	body	string	—	Model names the unit the amount prices (a machine size, a model id), and is recorded with the debit.
`org`	body	string	—	Org is the organization this usage is billed to.
`project`	body	string	—	Project attributes the debit to one project of the org.
`service`	body	string	—	Service scopes the debit for spend caps and attributes it to a product, as a lowercase slug.

Response

Status	Body	Meaning
`200`	billing.usageReceipt	ok
`default`	problem-details	refused

200 body — 6 fields.

Field	In	Type	Always	Description
`account`	body	string	—	Account is the wallet the debit drew from, the same key GET /v1/billing/balance reports for this caller.
`amount`	body	billing.Money	—
`amount.currency`	body	string	yes
`amount.decimal`	body	string	yes
`id`	body	string	—	ID is the act's name, echoed.
`org`	body	string	—	Org is the organization whose ledger holds the debit.

Failure carries the platform error shape — see Errors.

Examples

hanzo billing usage create

import { Configuration, BillingApi } from 'hanzoai';

const api = new BillingApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postBillingUsage({ amount: {"decimal":"<decimal>","currency":"<currency>"}, id: "<id>" });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BillingApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BillingApi(client).post_billing_usage(amount={"decimal":"<decimal>","currency":"<currency>"}, id="<id>")

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.BillingAPI.PostBillingUsage(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, billing_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = billing_api::post_billing_usage(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BillingApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new BillingApi(client).postBillingUsage();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X POST https://api.hanzo.ai/v1/billing/usage \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "amount": {
         "decimal": "<decimal>",
         "currency": "<currency>"
       },
       "id": "<id>"
     }'

MCP reaches billing through the billing tool, which names its 9 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_billing_balance"
         }
       }
     }'

Billing API · All Hanzo APIs · Interactive reference

Request

Response

Examples

On this page