Send an invoice to a client

send_invoice takes a request_id and an invoice_id, emails the invoice with the PDF attached, and advances a draft to sent. It refuses paid or cancelled invoices, and defaults the recipient to the client email when you omit one.

Written and reviewed by the Billr team. Published 2026-09-20, last reviewed 2026-09-20.

Who this is for: People who want the document delivered from the same session that drafted it.
Billr capabilities used: send_invoiceget_invoiceget_invoice_link

What you need first

A draft invoice, because sending is what advances it.
A key with the billing or full profile: send_invoice needs the send scope.
A client with an email address on file, or an explicit to address.

Step by step

01Confirm the draft is final
Sending freezes the numbers. Read the draft with get_invoice and correct anything wrong with update_draft_invoice first.

02Send with a request_id

The request id makes the call safe to retry. to defaults to the client email, and cc, bcc, subject and message are optional.

send_invoice  {
  "request_id": "5d3c9e21-8a4b-4f70-9c15-2b6e8d4a0f37",
  "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11",
  "message": "Thanks again for the September sprint."
}

03Check what the client receives
The email carries the invoice summary and the PDF. The same document is always available at its public link, which get_invoice_link returns.
04Watch the status change
A sent invoice moves to sent, then to viewed when the client opens the public page, and to partial or paid once payments are recorded.

Worked example

Fictional account, field names as returned by the server

You say

Send INV-1150 to Harbor & Lane.

Your agent calls

send_invoice { "request_id": "5d3c9e21-8a4b-4f70-9c15-2b6e8d4a0f37", "invoice_id": "6b1f0c62-6a0f-4f38-9d0e-3a1f9a2b7c11" }

Expected response, abridged

{
  "summary": "Sent INV-1150 to accounts@harbor-lane.example with PDF attached.",
  "to": "accounts@harbor-lane.example",
  "public_url": "https://billr.cc/i/2cQ7f1RtKp"
}

Limits and gotchas

Sending needs the billing or full key profile. A Read and draft key can prepare the document but not deliver it.
Ordinary invoice sending does not require human approval. Human approval applies to task pricing and task invoice approval, which are separate tools.
Already paid or cancelled invoices refuse to send, and a client without an email needs an explicit to.
Delivery depends on the sending configuration for the installation; a self-hosted copy uses its own email provider, not the hosted one.

Troubleshooting

The call is refused with a permission message: The key does not have the send scope. Create a billing key, or send the invoice from the dashboard instead.
Nothing arrives in the client inbox: Check the recipient on the result, then the spam folder. If the installation has no mail provider configured, delivery fails before the client sees anything.
The invoice was already sent: It still shows sent, and sending again is allowed only while the status permits it. Use get_invoice_link to hand the client the link rather than re-sending the email.

Sources

Reviewed 2026-09-20 against Billr's own tool implementations and the client documentation linked above.