Client Invoices

How to draft, issue, send and repeat invoices you write yourself, and how clients pay them online through your gateways. It covers invoice states, the pay page and its PDF, reminders, repeating schedules, refunds and the email templates.

Turn on the Client Invoices module (client_invoices toggle). It needs Licensing and Payments.

States

State	Meaning
draft	Being written. No number until it’s issued.
issued	Sent and awaiting payment. Shown as Overdue once the due date has passed.
paid	Paid online or marked paid.
void	Canceled. No payment is due.
refunded	The payment was refunded at the provider.

Moves between states:

• Issue a draft: it gets a number and a payment link. The total must be above zero, and the admin issues the version whose totals they reviewed. Issuing can email the client invoice_issued right away, or you send it later (and resend it, or send a reminder by hand).
• Reopen an issued, unpaid invoice: it goes back to draft and keeps its number. Old payment links stop working.
• Void a draft or an unpaid invoice: its payment link stops working. Voiding an issued invoice emails the client invoice_void unless you choose not to notify. A paid invoice can’t be voided; refund it instead.
• Mark paid for money received outside the store, such as a bank transfer. It goes through the same ledger and fulfillment as an online payment, once per invoice version.
• Delete only a draft that was never issued.
• Duplicate makes a new draft with the same customer and lines.

Each change is one guarded write on the invoice, so two admins (or an admin and an agent) can’t both apply conflicting changes; the second one sees a conflict. Every change is recorded in the invoice’s activity log.

Numbers

Client invoices take their numbers from the store’s one invoice series, shared with order invoices. Prefix and digits are the order invoice settings (invoice_prefix, invoice_padding); there’s no separate client invoice prefix. A number already used by another document is skipped.

The pay page

/_vendwick/pay/<code>?key=<key> is the client’s invoice and payment page.

• The code is ten random characters, never the invoice id. The key is signed over the code and the invoice’s revision, so editing, reopening or voiding an invoice revokes old links.
• An issued, unpaid invoice shows the payment methods routed for its currency. A paid, void or refunded invoice shows its status instead of a pay button.
• After paying, the provider returns the client here and the page says the payment is being confirmed. The invoice becomes paid when the payment is confirmed, and the client gets the invoice_paid receipt. You get the usual new-order notice (admin_order).
• The page is sent no-store, noindex and no-referrer.
• PDF: add &format=pdf (the page’s "Download PDF" link does) for the same invoice as a PDF file, with the same key rules: a wrong key, an old revision’s key or a draft is the same "unavailable" page. An issued or overdue invoice’s PDF carries a "Pay this invoice online" link back to this page; the payment panel itself isn’t part of the PDF. In the admin, the invoice screen’s PDF button downloads any invoice, drafts included (a draft is rendered each time and never stored). Engines, the cache and what the built-in engine can’t draw are the same as for order invoices: see PDF downloads.

Reminders

Settings:

• client_invoice_reminder_steps: up to four steps timed from the due date, such as before:3, on, after:3 (default before:3, after:3). Steps go out from 09:00 UTC. Steps before or on the due date use invoice_reminder; steps after it use invoice_overdue.
• client_invoice_after_issue_days: for invoices with no due date, one reminder this many days after issue (default 7, 0 turns it off).
• client_invoice_due_days: the default due date for new invoices (default 14 days, 0 means due on receipt).
• client_invoice_terms: default payment terms text.

Steps that were already past when the invoice was issued, or are more than a week old, are never sent. Each step is sent once. Reminders can be turned off per invoice. An hourly job sends them.

Repeating invoices

An invoice can be the template for a schedule (each period copies it):

• every 1 to 12 weeks, months or years, starting on a date after today;
• ending never, after 1 to 500 invoices, or on a date;
• each period’s invoice is either issued and emailed, or saved as a draft for you to check.

The hourly job creates each period’s invoice at 08:00 UTC with its own number and payment link. Dates count from the start date, so a schedule on the 31st runs on the last day of shorter months and returns to the 31st afterward. Overlapping runs never bill the same period twice, and a run that crashed is picked up where it stopped. Failed runs back off 1, 2, 4, 8 and 16 hours, then daily. After downtime, one invoice is created and the periods that were missed are logged as skipped, not billed.

Refunds

A paid client invoice has an order, which you refund from Orders like any other (see Refunds and Disputes), or in the provider’s dashboard. When the order is fully refunded, the invoice becomes refunded and the client gets invoice_refunded. A partial refund leaves the invoice paid; the order shows the refund and its credit note. An invoice you marked paid by hand (a bank transfer, for example) has no provider payment to refund from the admin.

Saved items and agents

Line items you reuse can be saved and picked from a list (invoiceItems). The client invoice abilities are also MCP tools, and agent creates are idempotent: repeating a create request returns the same invoice (invoiceRequests).

Emails

Template	Tags in the default
invoice_issued	site_name, invoice_number, amount, customer_name, invoice_title, due_date, invoice_lines, invoice_message, pay_url, invoice_pdf_url
invoice_reminder	invoice_number, due_date, customer_name, amount, pay_url
invoice_overdue	invoice_number, customer_name, amount, due_date, pay_url
invoice_paid	invoice_number, customer_name, amount, invoice_lines, pay_url, invoice_pdf_url
invoice_void	invoice_number, customer_name, amount
invoice_refunded	invoice_number, customer_name, amount, pay_url

{invoice_pdf_url} (0.2.0) is the pay page link with &format=pdf, available in every client invoice template. The default invoice and receipt emails end with "Download your invoice (PDF): …"; templates you edited keep your text, so add the tag yourself if you want the line. Emails can’t carry attachments in EmDash, so the PDF is always a link.

They’re plain text while the emails module is off and branded when it’s on, like every other template. See Customer Emails and Order Invoices.

Limits

• One currency per invoice, and only currencies your currency routes can take.
• No partial payments.
• The built-in PDF engine draws Western European (WinAnsi) text only; see PDF downloads for the optional engine that draws any script.
• All dates are UTC, because EmDash has no site timezone setting.