Invoices

Use these tools to create, update, and manage invoices — the billable documents you send to customers asking for payment.

In Zoop, every invoice starts as a draft and moves forward through a fixed set of statuses: draft → sent → paid (or overdue). When an invoice is no longer needed, you void it — voiding hides it from the default list but keeps the billing history intact. You cannot un-void an invoice.

Line items (the individual charges on an invoice) are covered by the same scope as the invoice itself — there is no separate read:invoice_line_items scope. See scopes.

Scopes

write:invoices does not include read:invoices. Grant both if your integration needs to read and write.

User actor requirement

invoices.create and invoices.update require a user actor — meaning the token must be tied to a real Zoop team member. Zoop records that team member's ID on every invoice for attribution.

There are two types of API keys:

• Tenant key (zoop_tk_ prefix) — represents the account as a whole, with no individual user identity attached. Calling invoices.create or invoices.update with a tenant key returns an invalid_input error.
• User key (zoop_uk_ prefix) — bound to a specific team member. Use this type for creating or updating invoices. You can issue a zoop_uk_ key to a dedicated service account team member for automated integrations.

See API keys for how to issue each type.

invoices.void does not require a user actor and works with either token type.

Invoice lifecycle

An invoice can only be in one status at a time, and it can only move forward — not backward. The table below shows what each status means and which transitions are allowed.

You can move a non-voided invoice to a new status at any time using invoices.update. However, editing any other field — notes, dates, line items, customer — is only allowed while the invoice is still in draft status. Trying to change those fields on a sent or paid invoice returns a conflict error.

Tools

invoices.list

Returns a list of your invoices, newest first. Voided invoices are excluded from the default results — pass status: "void" to see them explicitly. Results are paginated at 20 rows per page.

Scope: read:invoices

Returns: { data, count, page, limit }

Each item in data is a full invoice row. count is the total number of matching rows across all pages. limit is 20.

invoices.get

Fetches a single invoice by its ID, including all fields and computed totals (subtotal, tax, total).

Scope: read:invoices

Returns the full invoice record. Returns not_found if the invoice does not exist in this tenant.

invoices.create

Creates a new invoice in draft status. You supply the customer and line items; Zoop computes the subtotal, tax, and total for you — do not calculate or pass those values yourself.

Scope: write:invoices — requires a user actor (a zoop_uk_ key).

Returns the created invoice record. The status is "draft" and the total, subtotal, and tax_amount fields contain the server-computed values.

invoices.update

Updates an invoice. Only the fields you include in the request are changed — you do not need to resend the entire record.

Scope: write:invoices — requires a user actor (a zoop_uk_ key).

You can change the status on any non-voided invoice. All other fields — notes, issued_at, due_at, customer_id, default_tax_rate_id, and line_items — can only be changed while the invoice is in draft status. Sending those fields on a non-draft invoice returns a conflict error.

When you include line_items, the existing line items are replaced in full and totals are recomputed. Send line_items: [] to remove all line items.

Returns the updated invoice record on success. Returns not_found if the invoice does not exist. Returns conflict if you attempt to edit a non-status field on a non-draft invoice.

invoices.void

Voids an invoice. The invoice is hidden from the default list, but the billing history record is preserved. This action is permanent — a voided invoice cannot be un-voided.

Scope: write:invoices

Returns { voided: true, id } on success. Returns not_found if the invoice does not exist in this tenant.

Example: create and send an invoice

The steps below walk through the full create-and-send flow for a single visit invoice. Replace zoop_uk_<your-secret> with your own user key, and replace the UUID placeholders with real IDs from your tenant.

curl -X POST https://app.zoop.example/api/mcp \
  -H "Authorization: Bearer zoop_uk_<your-secret>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "invoices.create",
      "arguments": {
        "customer_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
        "issued_at": "2026-06-13T00:00:00Z",
        "due_at": "2026-07-13T00:00:00Z",
        "notes": "Thank you for the work order.",
        "line_items": [
          {
            "description": "HVAC tune-up — 2-ton split system",
            "quantity": 1,
            "unit_price": 185.00,
            "is_taxable": true,
            "tax_rate_id": "tttttttt-tttt-tttt-tttt-tttttttttttt"
          },
          {
            "description": "Refrigerant top-off (1 lb R-410A)",
            "quantity": 1,
            "unit_price": 45.00,
            "is_taxable": true,
            "tax_rate_id": null
          }
        ],
        "default_tax_rate_id": "tttttttt-tttt-tttt-tttt-tttttttttttt"
      }
    }
  }'

curl -X POST https://app.zoop.example/api/mcp \
  -H "Authorization: Bearer zoop_uk_<your-secret>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "invoices.update",
      "arguments": {
        "id": "iiiiiiii-iiii-iiii-iiii-iiiiiiiiiiii",
        "status": "sent"
      }
    }
  }'

A successful create response looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{"id":"iiiiiiii-iiii-iiii-iiii-iiiiiiiiiiii","tenant_id":"tttttttt-tttt-tttt-tttt-tttttttttttt","customer_id":"cccccccc-cccc-cccc-cccc-cccccccccccc","invoice_number":"INV-0001","status":"draft","subtotal":230.00,"tax_amount":19.00,"total":249.00,"issued_at":"2026-06-13T00:00:00Z","due_at":"2026-07-13T00:00:00Z","notes":"Thank you for the work order.","created_at":"2026-06-13T10:00:00Z"}"
      }
    ]
  }
}

Example: list open invoices

The request below fetches the first page of sent invoices — the ones that have been sent to customers but not yet paid.

curl -X POST https://app.zoop.example/api/mcp \
  -H "Authorization: Bearer zoop_uk_<your-secret>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "invoices.list",
      "arguments": {
        "status": "sent",
        "page": 1
      }
    }
  }'

Pagination

invoices.list returns up to 20 invoices per request (one page). If your tenant has more than 20 matching invoices, you need to make multiple requests and stitch the results together. The response includes a count field — the total number of matching invoices across all pages — which lets you calculate how many pages exist. Increment page by one on each request until you have fetched them all.

The TypeScript example below shows a simple loop:

let page = 1
const limit = 20
let allInvoices: unknown[] = []

while (true) {
  const response = await fetch('https://app.zoop.example/api/mcp', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ZOOP_API_KEY}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json, text/event-stream',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: page,
      method: 'tools/call',
      params: {
        name: 'invoices.list',
        arguments: { status: 'sent', page },
      },
    }),
  })

  const envelope = await response.json()
  const text = envelope.result?.content?.[0]?.text
  const result = JSON.parse(text)

  allInvoices = allInvoices.concat(result.data)

  const totalPages = Math.ceil(result.count / limit)
  if (page >= totalPages) break
  page++
}

Error reference

Every error response includes a kind field. The table below covers the errors specific to invoice tools.

See errors for the full error reference and HTTP status codes.

Related

• Invoices in Zoop — end-user guide for working with invoices in the product
• Tax rates — manage the tax rates you can reference on line items
• Quotes — the pre-invoice estimating step
• Jobs — jobs that invoices can be linked to
• Scopes — full scope catalog
• Authentication — how to authenticate requests
• MCP server — transport, conventions, and the full tool catalog
• Errors — error kinds and HTTP status codes