REST API Reference

Generate api keys inside the Organization Settings → API Keys page. All API keys must be kept private and secure. Include the key as a Bearer token in the request header:

Authorization: Bearer sk_live_your_key

Submit a POST request with details such as client billing details and nested line items:

curl -X POST https://app.invforge.com/api/public/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Apex Manufacturing Co.",
    "client_address": "890 Industrial Park Road, Dallas, TX 75201",
    "client_email": "[email protected]",
    "currency": "USD",
    "issue_date": "2026-07-26",
    "items": [
      {
        "description": "Industrial Equipment Maintenance",
        "qty": 6,
        "rate": 1200,
        "tax": 8.25
      }
    ],
    "status": "draft"
  }'

The create response includes invoice_url, a shareable URL for viewing the invoice. If client editing is enabled for the organization, the same URL lets the client update their name, address, and VAT details during the edit window.

{
  "id": "inv_123",
  "number": "INV-0042",
  "status": "draft",
  "total": 3300,
  "invoice_url": "https://app.invforge.com/i/9d4c7f..."
}

List invoices for your organization. Results are newest first and support pagination and status filtering.

curl "https://app.invforge.com/api/public/v1/invoices?limit=20&offset=0&status=paid" \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [{ "id": "inv_123", "number": "INV-0042", "status": "paid", "total": 3300 }],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Fetch one invoice by its ID. IDs are returned by the create and list endpoints.

curl https://app.invforge.com/api/public/v1/invoices/inv_123 \
  -H "Authorization: Bearer sk_live_..."

PATCH changes only the fields you send. Omitted fields remain unchanged. Send null for nullable fields such as due_date, notes, or terms.

curl -X PATCH https://app.invforge.com/api/public/v1/invoices/inv_123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "client_email": "[email protected]",
    "due_date": "2026-08-30",
    "notes": "Please pay by bank transfer.",
    "items": [
      { "description": "Monthly support", "qty": 2, "rate": 750, "tax": 8.25 }
    ]
  }'

To clear a value, explicitly send null. To replace line items, send the complete new items array.

curl -X PATCH https://app.invforge.com/api/public/v1/invoices/inv_123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "notes": null, "terms": null, "shipping": 25 }'

Delete an invoice permanently. This action cannot be undone. The API also emits an invoice.deleted webhook.

curl -X DELETE https://app.invforge.com/api/public/v1/invoices/inv_123 \
  -H "Authorization: Bearer sk_live_..."

{ "ok": true, "id": "inv_123" }

Use the status endpoint when you want a focused state transition. Valid values are draft, sent, and paid.

curl -X POST https://app.invforge.com/api/public/v1/invoices/inv_123/status \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Status changes can trigger invoice.status_changed and, for paid invoices, invoice.paid.

Clients are organization-scoped. Create a reusable client record, then use the returned details when creating invoices.

curl -X POST https://app.invforge.com/api/public/v1/clients \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Apex Manufacturing Co.",
    "email": "[email protected]",
    "address": "890 Industrial Park Road, Dallas, TX 75201"
  }'

Creating an invoice does not require a client record; you can always provide client_name, client_email, and client_address directly.

You can set discounts or taxes either at the top-level invoice layer or per individual line items.

• discount_type: can be "percent" or "fixed".
• discount_value / discount: represents the actual value depending on the type.

InvForge uses standard HTTP codes to denote request outcomes: