Create an invoice with AI

---
name: create-invoice
description: Create a Hyperline invoice through the public API. Use when an agent needs to draft or execute a POST /v1/invoices payload with customer_id, explicit status, line_items, payment settings, and optional custom properties.
---

# Create Invoice

Use the public API endpoint `POST /v1/invoices`.

## Inputs

Collect these values before calling the API:

- `customer_id`: Hyperline customer ID.
- `status`: usually `draft` or `to_pay`.
- `line_items`: at least one line item.
- Optional `currency`, `subscription_id`, `due_at`, `emitted_at`, `payment_method_strategy`, `custom_properties`, `purchase_order`, and invoice notes.

If the user gives product names instead of IDs, resolve product IDs first. Do not guess.

## Payload

Draft invoice with a catalog product:

```json
{
  "customer_id": "cus_xxx",
  "status": "draft",
  "line_items": [
    {
      "product_id": "prod_xxx",
      "units_count": 1,
      "unit_amount": 10000,
      "tax_rate": 20
    }
  ]
}
```

Draft invoice with an ad hoc line item:

```json
{
  "customer_id": "cus_xxx",
  "status": "draft",
  "currency": "EUR",
  "line_items": [
    {
      "name": "Implementation fee",
      "unit_amount": 50000,
      "units_count": 1,
      "tax_rate": 20
    }
  ]
}
```

Call shape:

```bash
curl -X POST "https://api.hyperline.co/v1/invoices" \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '<payload>'
```

## Safety

- Always set `status` explicitly. Use `draft` unless the user clearly wants the invoice issued.
- Do not set `paid` unless the user explicitly says the invoice is already paid.
- Use `payment_method_strategy: "external"` only when payment is handled outside Hyperline.
- Include `subscription_id` only when the invoice should be linked to an existing subscription.

## Verify

After creation:

1. Read `id`, `status`, `customer_id`, `amount_excluding_tax`, and `amount_including_tax` from the response.
2. Fetch `GET /v1/invoices/{id}` if you need to confirm line items.
3. If the invoice should be sent or charged, ask for explicit confirmation before taking the next action.