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)
• The Invoica SDK installed (npm install @invoica/sdk)

Step 1: Initialize the Client

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.

Base (default)

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: '[e-mail]',
    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',
  },
});

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: '[e-mail]',
  },
  seller: {
    name: 'My AI Platform',
    // Base58-encoded Solana wallet address
    wallet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  },
});

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: '[e-mail]',
  },
  seller: {
    name: 'My AI Platform',
    wallet: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18',
  },
});

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

Response

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

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

// 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

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 to receive real-time invoice status updates
• Configure tax compliance for automatic tax calculation
• Explore the full API for advanced invoice operations