# Create invoices

URL: https://docs.hanzo.ai/docs/openapi/billing/raiseinvoice

> Raises a DRAFT invoice against a customer in the caller's own org.

`POST /v1/billing/invoices`

> [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/invoices` |
| **Method**    | `POST`                                     |
| **Operation** | `raiseInvoice`                             |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`     |

Raises a DRAFT invoice against a customer in the caller's own org. It is the
org admin's act; a member is refused 403.

The invoice is not collectible yet: a draft exists so it can be read and
corrected, and issueInvoice is the separate act that turns it into a demand for
payment. The subtotal and amount due are computed from the lines, so there is
no total to send and none to get wrong.

The billing org is the caller's, taken from the validated principal, so an
invoice can only ever be raised on the caller's own books.

A named handler, not a closure, so zipdoc can lift this prose into the registry.

## Request

8 fields, body `application/json` (required).

| Field                 | In   | Type                   | Required | Description                                                                |
| --------------------- | ---- | ---------------------- | -------- | -------------------------------------------------------------------------- |
| `currency`            | body | string                 | —        | Currency is the ISO 4217 code, lower-cased.                                |
| `customerEmail`       | body | string                 | —        | CustomerEmail is where the invoice is sent.                                |
| `lines`               | body | billing.InvoiceLine\[] | —        | Lines are the charges.                                                     |
| `lines[].amount`      | body | integer (int64)        | —        | Amount is the line total in whole cents (250000 is $2,500.00).             |
| `lines[].description` | body | string                 | —        | Description is the human-readable line, e.g. "Advisory retainer — August". |
| `lines[].quantity`    | body | integer (int64)        | —        | Quantity is the number of units, when the line is metered.                 |
| `lines[].unitPrice`   | body | integer (int64)        | —        | UnitPrice is the per-unit price in cents, when the line is metered.        |
| `userId`              | body | string                 | —        | UserID identifies the customer being billed, within the caller's own org.  |

## Response

| Status    | Body            | Meaning |
| --------- | --------------- | ------- |
| `201`     | billing.Invoice | created |
| `default` | problem-details | refused |

`201` body — 16 fields.

| Field                 | In   | Type                   | Always | Description                                                                |
| --------------------- | ---- | ---------------------- | ------ | -------------------------------------------------------------------------- |
| `amountDueCents`      | body | integer (int64)        | —      | AmountDueCents is what remains collectible.                                |
| `amountPaidCents`     | body | integer (int64)        | —      | AmountPaidCents is what has been collected so far.                         |
| `createdAt`           | body | string                 | —      | CreatedAt is when the draft was raised, RFC3339.                           |
| `currency`            | body | string                 | —      | Currency is the ISO 4217 code.                                             |
| `customerEmail`       | body | string                 | —      | CustomerEmail is where it is sent.                                         |
| `id`                  | body | string                 | —      | ID is the invoice id — what the issue, collect and void ops address.       |
| `lines`               | body | billing.InvoiceLine\[] | —      | Lines are the charges on the invoice.                                      |
| `lines[].amount`      | body | integer (int64)        | —      | Amount is the line total in whole cents (250000 is $2,500.00).             |
| `lines[].description` | body | string                 | —      | Description is the human-readable line, e.g. "Advisory retainer — August". |
| `lines[].quantity`    | body | integer (int64)        | —      | Quantity is the number of units, when the line is metered.                 |
| `lines[].unitPrice`   | body | integer (int64)        | —      | UnitPrice is the per-unit price in cents, when the line is metered.        |
| `number`              | body | string                 | —      | Number is the human-facing invoice number, e.g. "INV-0042".                |
| `paymentRef`          | body | string                 | —      | PaymentRef is the processor reference for the collection, once paid.       |
| `status`              | body | string                 | —      | Status is draft, open, paid, void or uncollectible.                        |
| `subtotalCents`       | body | integer (int64)        | —      | SubtotalCents is the sum of the lines.                                     |
| `userId`              | body | string                 | —      | UserID is the customer billed.                                             |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo billing invoices 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.raiseInvoice({ currency: "<currency>", customerEmail: "<customerEmail>" });
```

**.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).raise_invoice(currency="<currency>", customer_email="<customerEmail>")
```

**.go**

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

resp, _, err := client.BillingAPI.RaiseInvoice(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::raise_invoice(&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).raiseInvoice();
```

**HTTP**

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

**MCP**

Tool `billing`, op `raiseInvoice` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`.

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "billing",
         "arguments": {
           "op": "raiseInvoice",
           "input": {
             "currency": "<currency>",
             "customerEmail": "<customerEmail>"
           }
         }
       }
     }'
```

---

[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)