---
name: givegigs-invoices
description: Generate professional invoices, attach logged time entries, manage billing clients, and configure tax settings.
---

# Invoices & Billing Management

Base URL: `https://givegigs.com`. Authenticate with `Authorization: Bearer givegigs-...` or `X-API-Key`. Private reads require `read` scope; mutations require `write` scope.

Web interface: `https://givegigs.com/invoice`.

## Create an Invoice

```http
POST /api/invoice
Content-Type: application/json
Authorization: Bearer givegigs-...

{
  "number": "INV-2026-0042",
  "date": "2026-10-29T00:00:00Z",
  "dueDate": "2026-11-15T00:00:00Z",
  "clientId": "inv_client_abc",
  "currency": "USD",
  "taxRate": 8.25,
  "items": [
    {
      "description": "Inventory Lot Sourcing & Manifest Valuation",
      "quantity": 1,
      "unitPrice": 450.00,
      "amount": 450.00
    }
  ],
  "timeEntryIds": ["time_entry_1", "time_entry_2"],
  "notes": "Thank you for your business. Payment due via direct bank transfer.",
  "status": "PENDING"
}
```

### Constraints & Invoicing Rules
- `number`, `date`, and `dueDate` are required. Dates must be valid ISO-8601 strings.
- `timeEntryIds` atomically marks attached time entries as invoiced. Prevents double-billing via `InvoiceTimeConflict` protection.
- `autoNumber`: pass `true` to have GiveGigs assign the next sequential invoice number based on user settings.

## Manage Invoices

- `GET /api/invoice?status=PENDING&limit=25` - List user invoices with filters.
- `GET /api/invoice/:id` - Full invoice detail including line items, recipient data, and PDF metadata.
- `PUT /api/invoice/:id` - Update draft or pending invoice.
- `DELETE /api/invoice/:id` - Soft-deletes invoice to trash.

## Billing Clients

- `GET /api/invoice/clients` - List saved invoice billing clients.
- `POST /api/invoice/clients` - Create client: `{ "name": "Acme Resale Corp", "email": "billing@acmeresale.com", "address": "456 Market St, Austin, TX", "taxId": "XX-XXXXXXX", "currency": "USD" }`.
- `PUT/DELETE /api/invoice/clients/:id` - Update or delete a client record.

## Settings & Trash

- `GET /api/invoice/settings` / `PUT /api/invoice/settings` - Business name, default payment terms, tax defaults, and logo preferences.
- `GET /api/invoice/trash` - View soft-deleted invoices. Purge or restore via `/api/invoice/trash/:id`.

[Light Skill](https://givegigs.com/skill.md) · [Complete Reference](https://givegigs.com/skill-heavy.md)