How to Automate Invoicing with the CleverInvo API

If you send more than a handful of invoices each month, you have probably wished you could automate the process. Maybe you want invoices to be generated automatically when a project completes in your project management tool. Or you want your CRM to create invoices when a deal closes. Or you simply want to batch-generate monthly invoices for all your retainer clients without clicking through a form fifty times.

The CleverInvo API makes all of this possible. This guide covers the fundamentals: authentication, creating clients, generating invoices, and setting up webhooks to react to invoice events.

---

Prerequisites

The API is available on the Business tier. You will need:

1. A CleverInvo account on the Business plan
2. An API key (generate one from Dashboard > API Keys)
3. Basic familiarity with REST APIs and JSON

All API requests use HTTPS and return JSON responses. The base URL is:

https://cleverinvo.com/api/v1

Authentication

Include your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients

All requests without a valid API key receive a 401 Unauthorized response.

---

Managing Clients

Before creating an invoice, you need a client on file. The Clients API handles this.

Create a Client

curl -X POST https://cleverinvo.com/api/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "email": "[email protected]",
    "address": "123 Business Ave, Suite 400\nNew York, NY 10001",
    "taxId": "US-EIN-12-3456789",
    "phone": "+1-555-0100"
  }'

Response:

{
  "id": "cli_abc123def456",
  "name": "Acme Corporation",
  "email": "[email protected]",
  "address": "123 Business Ave, Suite 400\nNew York, NY 10001",
  "taxId": "US-EIN-12-3456789",
  "phone": "+1-555-0100",
  "isActive": true,
  "createdAt": "2026-03-01T10:00:00.000Z"
}

List Clients

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://cleverinvo.com/api/v1/clients?page=1&limit=20"

Get, Update, or Delete a Client

# Get
curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients/cli_abc123def456

# Update
curl -X PUT https://cleverinvo.com/api/v1/clients/cli_abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+1-555-0200"}'

# Delete
curl -X DELETE -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/clients/cli_abc123def456

---

Creating Invoices

This is where the real value of the API shines. You can generate professional, numbered invoices with a single API call.

Create an Invoice

curl -X POST https://cleverinvo.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cli_abc123def456",
    "currency": "USD",
    "issueDate": "2026-03-01",
    "dueDate": "2026-03-31",
    "lineItems": [
      {
        "description": "Website redesign - Phase 1",
        "quantity": 1,
        "unitPrice": 5000.00
      },
      {
        "description": "Frontend development",
        "quantity": 40,
        "unitPrice": 150.00
      },
      {
        "description": "Content migration",
        "quantity": 8,
        "unitPrice": 100.00
      }
    ],
    "notes": "Thank you for your business.",
    "terms": "Payment due within 30 days. Late payments subject to 1.5% monthly interest."
  }'

Response:

{
  "id": "inv_xyz789ghi012",
  "invoiceNumber": "INV-0001",
  "clientId": "cli_abc123def456",
  "currency": "USD",
  "issueDate": "2026-03-01T00:00:00.000Z",
  "dueDate": "2026-03-31T00:00:00.000Z",
  "lineItems": [
    {"description": "Website redesign - Phase 1", "quantity": 1, "unitPrice": 5000.00, "amount": 5000.00},
    {"description": "Frontend development", "quantity": 40, "unitPrice": 150.00, "amount": 6000.00},
    {"description": "Content migration", "quantity": 8, "unitPrice": 100.00, "amount": 800.00}
  ],
  "subtotal": 11800.00,
  "taxTotal": 0,
  "discountTotal": 0,
  "total": 11800.00,
  "status": "DRAFT",
  "pdfUrl": "https://storage.cleverinvo.com/invoices/inv_xyz789ghi012.pdf",
  "createdAt": "2026-03-01T10:30:00.000Z"
}

The system automatically:

• Assigns the next sequential invoice number
• Calculates line totals, subtotal, and total
• Generates a PDF and returns the URL
• Sets the status to DRAFT

Invoice with Tax

To include tax, add a taxRate to each line item:

{
  "lineItems": [
    {
      "description": "Consulting services",
      "quantity": 20,
      "unitPrice": 200.00,
      "taxRate": 20
    }
  ]
}

The API will calculate the tax amount per line and include taxTotal in the response.

---

Managing Invoice Status

Invoices move through a lifecycle: DRAFT, SENT, VIEWED, PAID, PARTIALLY_PAID, OVERDUE.

Update Status

# Mark as sent
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "SENT"}'

# Mark as paid
curl -X PATCH https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "PAID"}'

Download the PDF

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://cleverinvo.com/api/v1/invoices/inv_xyz789ghi012/pdf \
     --output invoice.pdf

---

Common Integration Patterns

Pattern 1: CRM to Invoice

When a deal closes in your CRM, automatically create a client (if new) and generate an invoice:

// Pseudocode for a CRM webhook handler
async function onDealClosed(deal) {
  // Find or create the client
  let client = await cleverinvo.clients.findByEmail(deal.customerEmail);
  if (!client) {
    client = await cleverinvo.clients.create({
      name: deal.customerName,
      email: deal.customerEmail,
      address: deal.customerAddress,
    });
  }

  // Create the invoice
  const invoice = await cleverinvo.invoices.create({
    clientId: client.id,
    currency: deal.currency,
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems: deal.products.map((p) => ({
      description: p.name,
      quantity: p.quantity,
      unitPrice: p.price,
    })),
  });

  console.log(`Invoice ${invoice.invoiceNumber} created for ${client.name}`);
}

Pattern 2: Monthly Retainer Billing

Generate invoices for all retainer clients on the 1st of each month:

// Run via cron job on the 1st of each month
async function generateMonthlyInvoices() {
  const clients = await cleverinvo.clients.list({ isActive: true });
  const today = new Date();
  const dueDate = addDays(today, 30);

  for (const client of clients.data) {
    if (client.retainerAmount) {
      await cleverinvo.invoices.create({
        clientId: client.id,
        currency: "USD",
        issueDate: today.toISOString().split("T")[0],
        dueDate: dueDate.toISOString().split("T")[0],
        lineItems: [
          {
            description: `Monthly retainer - ${format(today, "MMMM yyyy")}`,
            quantity: 1,
            unitPrice: client.retainerAmount,
          },
        ],
        terms: "Net 30",
      });
    }
  }
}

Pattern 3: Time Tracking Integration

Pull hours from your time tracking tool and generate invoices:

async function invoiceTrackedHours(clientId, startDate, endDate) {
  // Fetch time entries from your tracking tool
  const entries = await timeTracker.getEntries({ clientId, startDate, endDate });

  // Group by project or task
  const lineItems = groupByProject(entries).map((group) => ({
    description: `${group.projectName} (${group.totalHours} hrs)`,
    quantity: group.totalHours,
    unitPrice: group.hourlyRate,
  }));

  const invoice = await cleverinvo.invoices.create({
    clientId,
    currency: "USD",
    issueDate: new Date().toISOString().split("T")[0],
    dueDate: addDays(new Date(), 30).toISOString().split("T")[0],
    lineItems,
    notes: `Hours tracked from ${startDate} to ${endDate}`,
  });

  return invoice;
}

---

Rate Limits

The API enforces rate limits to ensure fair usage:

Tier	Limit
Business	100 requests per minute

If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

---

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "clientId is required",
    "details": [
      {"field": "clientId", "message": "This field is required"}
    ]
  }
}

Common error codes:

Code	HTTP Status	Meaning
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	API access not available on your tier
NOT_FOUND	404	Resource does not exist
VALIDATION_ERROR	422	Invalid request data
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error (contact support)

---

Next Steps

The CleverInvo API is designed to fit into your existing workflow — whether that is a simple cron job or a complex multi-system integration. Start with a single use case, get it working, and expand from there.

Full API documentation is available at /docs/api, including OpenAPI specs and additional code examples.

Get your API key ->