Raise a draft invoice against a customer

POST /v1/billing/invoices

Billing → · All API references → · Six flows, four surfaces →


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.

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	InvoiceLine[]	—	Lines are the charges. The invoice subtotal and amount due are COMPUTED from these — there is no total field to send, because a total that disagreed with its…
`lines[].amount`	body	integer	—	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.
`lines[].quantity`	body	integer	—	Quantity is the number of units, when the line is metered.
`lines[].unitPrice`	body	integer	—	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`	Invoice	created

201 body — 16 fields.

Field	In	Type	Always	Description
`amountDueCents`	body	integer	—	AmountDueCents is what remains collectible.
`amountPaidCents`	body	integer	—	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	InvoiceLine[]	—	Lines are the charges on the invoice.
`lines[].amount`	body	integer	—	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.
`lines[].quantity`	body	integer	—	Quantity is the number of units, when the line is metered.
`lines[].unitPrice`	body	integer	—	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.
`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	—	SubtotalCents is the sum of the lines.
`userId`	body	string	—	UserID is the customer billed.

Failure carries the platform error shape — see Errors.

Examples

hanzo billing invoices create

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

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

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

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

use hanzo_cloud::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?;

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

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

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

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>"
     }'

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

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": "commerce",
         "arguments": {
           "op": "raiseInvoice",
           "input": {
             "currency": "<currency>",
             "customerEmail": "<customerEmail>"
           }
         }
       }
     }'

Billing API · All Hanzo APIs · Interactive reference

Raise a draft invoice against a customer

Request

Response

Examples

On this page