> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Invoice

> Create a draft invoice with optional line items and buyer address.

## Method

`POST` `/v1/billing/invoices`

## Body Parameters

<ParamField name="number" type="string">Custom invoice number (defaults to an auto-generated sequence).</ParamField>
<ParamField name="series" type="string">Series identifier (defaults to `INV`).</ParamField>
<ParamField name="currency" type="string">ISO 4217 currency (defaults to `USD`).</ParamField>
<ParamField name="issueDate" type="string">Issue date (ISO 8601). Optional.</ParamField>
<ParamField name="dueDate" type="string">Due date (ISO 8601). Optional.</ParamField>
<ParamField name="buyerAddress" type="object">Structured address object stored on the invoice.</ParamField>
<ParamField name="lines" type="array">Invoice lines. Each item supports `itemType`, `description`, `quantity`, `unit`, `unitPrice`, `discountAmount`, `taxRate`, `lineTotal`.</ParamField>

## Headers

<ParamField header="Authorization" type="string">Bearer token with `billing:write` scope.</ParamField>
<ParamField header="content-type" type="string">`application/json`</ParamField>

## Request Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.voyantcloud.com/v1/billing/invoices \
    -H "Authorization: Bearer $VOYANT_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "series": "INV",
      "currency": "EUR",
      "issueDate": "2025-02-15",
      "dueDate": "2025-03-01",
      "buyerAddress": {
        "company": "Voyant Travel SRL",
        "vat": "RO12345678",
        "country": "RO"
      },
      "lines": [
        {
          "itemType": "service",
          "description": "Summer cruise package",
          "quantity": 1,
          "unitPrice": 2450,
          "taxRate": 0,
          "lineTotal": 2450
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch("https://api.voyantcloud.com/v1/billing/invoices", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VOYANT_API_KEY}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      currency: "EUR",
      lines: [
        { description: "Deposit", quantity: 1, unitPrice: 500, lineTotal: 500 },
      ],
    }),
  })
  const { id } = await res.json()
  ```

  ```python Python theme={null}
  import os, requests

  payload = {
    "currency": "EUR",
    "buyerAddress": {"company": "Voyant Travel SRL", "country": "RO"},
    "lines": [{"description": "Deposit", "quantity": "1", "unitPrice": "500", "lineTotal": "500"}],
  }

  resp = requests.post(
    "https://api.voyantcloud.com/v1/billing/invoices",
    headers={
      "Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}",
      "content-type": "application/json",
    },
    json=payload,
  )
  invoice = resp.json()
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 201 Created theme={null}
  { "id": "4a9a807e-5c7c-4f57-8e6d-2c6f1b1c5d10" }
  ```

  ```json 400 Bad Request theme={null}
  { "error": "Missing workspace context" }
  ```
</ResponseExample>

<Tip>Workspace context is provided by the API key. Partner integrations that operate across multiple workspaces must call the endpoint once per workspace.</Tip>