# Create usage

URL: https://docs.hanzo.ai/docs/openapi/billing/post-billing-usage

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

`POST /v1/billing/usage`

> [Billing →](https://docs.hanzo.ai/docs/openapi/billing) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                         |
| ------------- | --------------------------------------- |
| **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](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo billing usage create
```

**SDK**

**.ts**

```ts
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>" });
```

**.py**

```python
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>")
```

**.go**

```go
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
}
```

**.rs**

```rust
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?;
```

**.java**

```java
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();
```

**HTTP**

```bash
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**

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

```bash
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": "list_billing_accounts"
         }
       }
     }'
```

---

[Billing API](https://docs.hanzo.ai/docs/openapi/billing) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)