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

# Create Your First Invoice

> Step-by-step guide to creating and managing invoices with the Invoica API.

# Create Your First Invoice

This guide walks you through creating an invoice, checking its status, and handling the complete lifecycle.

## Prerequisites

* An Invoica API key ([get one here](https://app.invoica.ai/api-keys))
* The Invoica SDK installed (`npm install @invoica/sdk`)

## Step 1: Initialize the Client

```typescript theme={null}
import { InvoicaClient } from '@invoica/sdk';

const client = new InvoicaClient({
  apiKey: process.env.INVOICA_API_KEY,
  baseUrl: 'https://api.invoica.ai',
});
```

## Step 2: Create an Invoice

Invoica supports four chains. Set the `chain` field to route settlement detection correctly.

<CodeGroup>
  ```typescript Base (default) theme={null}
  const invoice = await client.invoices.create({
    amount: 5000,        // $50.00 in cents
    currency: 'USD',
    chain: 'base',       // default if omitted
    description: 'GPT-4 API calls - Agent Alpha - February 2026',
    buyer: {
      companyName: 'Acme AI Corp',
      email: 'billing@acme-ai.com',
      address: '123 Agent Street, San Francisco, CA 94105',
      vat: 'US-987654321',
    },
    seller: {
      name: 'My AI Platform',
      address: '456 Tech Blvd, Austin, TX 78701',
      vat: 'US-123456789',
      wallet: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18',
    },
  });
  ```

  ```typescript Solana theme={null}
  const invoice = await client.invoices.create({
    amount: 5000,        // $50.00 in cents
    currency: 'USD',
    chain: 'solana',
    description: 'GPT-4 API calls - Agent Alpha - February 2026',
    buyer: {
      companyName: 'Acme AI Corp',
      email: 'billing@acme-ai.com',
    },
    seller: {
      name: 'My AI Platform',
      // Base58-encoded Solana wallet address
      wallet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
    },
  });
  ```

  ```typescript Polygon / Arbitrum theme={null}
  const invoice = await client.invoices.create({
    amount: 5000,
    currency: 'USD',
    chain: 'polygon',    // or 'arbitrum'
    description: 'GPT-4 API calls - Agent Alpha - February 2026',
    buyer: {
      companyName: 'Acme AI Corp',
      email: 'billing@acme-ai.com',
    },
    seller: {
      name: 'My AI Platform',
      wallet: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18',
    },
  });
  ```
</CodeGroup>

| `chain` value | Network                | Settlement token |
| ------------- | ---------------------- | ---------------- |
| `base`        | Base Mainnet (default) | USDC             |
| `polygon`     | Polygon Mainnet        | USDC             |
| `arbitrum`    | Arbitrum One           | USDC             |
| `solana`      | Solana Mainnet         | USDC (SPL)       |

### Response

```json theme={null}
{
  "id": "inv_8a7b6c5d4e3f2a1b",
  "invoiceNumber": "INV-2026-0001",
  "status": "draft",
  "amount": 5000,
  "currency": "USD",
  "tax": 412,
  "total": 5412,
  "createdAt": "2026-02-18T10:30:00Z",
  "buyer": { "companyName": "Acme AI Corp" },
  "seller": { "name": "My AI Platform" }
}
```

## Step 3: List Your Invoices

```typescript theme={null}
const { invoices, total, page } = await client.invoices.list({
  limit: 10,
  status: 'draft',
});

invoices.forEach(inv => {
  console.log(`${inv.invoiceNumber}: $${(inv.total / 100).toFixed(2)} - ${inv.status}`);
});
```

## Step 4: Monitor Invoice Status

```typescript theme={null}
// Poll for status changes
const checkStatus = async (invoiceId: string) => {
  const invoice = await client.invoices.get(invoiceId);
  console.log(`Status: ${invoice.status}`);
  return invoice.status;
};

// Or use webhooks (recommended for production)
// See the Webhooks guide for setup
```

## Invoice Status Flow

```
draft → sent → paid → settled → completed
```

Each status transition triggers a webhook event if configured.

## Error Handling

```typescript theme={null}
try {
  const invoice = await client.invoices.create(payload);
} catch (error) {
  if (error.status === 400) {
    console.error('Invalid invoice data:', error.message);
  } else if (error.status === 402) {
    console.error('Budget exceeded:', error.message);
  } else if (error.status === 429) {
    console.error('Rate limit hit, retrying...');
  }
}
```

## Next Steps

* [Set up webhooks](/guides/webhooks) to receive real-time invoice status updates
* [Configure tax compliance](/guides/tax-compliance) for automatic tax calculation
* [Explore the full API](/api-reference/invoices) for advanced invoice operations