Advance Invoices for WordPress & WooCommerce

1. Overview

Advance Invoices for WordPress & WooCommerce is a small invoicing application inside WordPress. You create invoices, optionally estimates, produce them as A4 PDF files, email them, share a private link with the customer, record or collect payments and issue numbered PDF receipts. This page documents version 1.1.0.

On the Plugins screen the plugin is listed under the same name, and its folder is wphub-advance-invoice. In the admin menu it appears as Invoices (and Estimates once you switch estimates on). Everything it stores uses the prefix wphub_invoice_.

It is written for freelancers, agencies and small businesses that want invoicing inside WordPress, and for WooCommerce stores that want a numbered PDF invoice on their order emails. WooCommerce is optional. Without it you type each customer in by hand and everything else works the same.

How it works

1. You enter your company details, currencies and numbering under Invoices → Settings.
2. You create a document under Invoices → Add New: a customer, one or more items, optional discount, shipping and tax. The server recalculates every total when you save, preview or print, so the figures on the PDF never come from the browser.
3. One renderer (the bundled Dompdf library) turns the document into a PDF. The preview, the download and the email attachment all come from it, so they match.
4. You email the PDF from the editor, or share the document's private link. The customer opens the link without logging in to view the document, download the PDF and, for invoices, pay with Stripe or PayPal.
5. Every payment is a row in a ledger. The invoice status (Partially Paid, Paid) follows the ledger, and each payment gets a numbered PDF receipt.

At a glance

What it does not do

• It does not work out tax for you. Tax is a percentage you type per item (and for shipping), added on top of the net amount. There are no tax tables, tax classes or tax-inclusive prices.
• It does not convert currencies. A document's currency only changes the symbol, position, decimals and separators.
• It does not send reminders, create recurring invoices, add late fees or issue credit notes. The daily job only changes statuses and sends no email. A WooCommerce refund becomes a negative credit line on the original invoice.
• It does not keep copies of PDF files. A PDF is generated each time it is previewed, downloaded, emailed or fetched from the client page.
• It has no customer login area, no shortcodes, no blocks, no REST API and no WP-CLI commands.
• It supports Stripe and PayPal only (another gateway can be added in code, see Hooks).
• One address per document (billing). A customer's shipping address can be copied into the fields instead, but it is not printed as a second block.
• The bundled PDF font (DejaVu Sans) has no Chinese, Japanese or Korean glyphs, and the templates set no right-to-left direction.

2. Requirements

3. Installation

Install and activate

1. Download the plugin zip from your account on wpexpertshub.com.
2. In WordPress open Plugins → Add New → Upload Plugin, choose the zip and click Install Now, then Activate.
3. Open Invoices → Settings and fill in Company, Currency and Invoice.
4. Optional but recommended: activate your licence (next section) to receive updates.

The plugin works as soon as it is activated. No licence key is checked anywhere in the invoicing code: the bundled client only handles activation, deactivation and update information.

Activate your licence (updates)

The plugin bundles the WpExperts Hub licence and update client (version 2.0.0 of the client). One screen manages every WpExperts Hub plugin on the site that bundles it.

1. Open Plugins → WpExperts Hub Licences, or click Licence under the plugin's name on the Plugins screen. Both are shown to users who can manage_options.
2. Paste the key from your purchase email (it is also shown under My Account → Downloads on wpexpertshub.com) and click Activate licence. Only letters, digits and hyphens are kept from what you paste.
3. The card for the plugin shows Active and the key in masked form (the first four and last four characters). New versions then appear in the normal WordPress updates screen and on the Plugins screen, and install like any other plugin update.
4. Lost your key? Open the line Can't find your key? Email it to me on the same screen, enter the email address used for the purchase and click Send licence key.
5. Before you move the plugin to another live site, click Deactivate licence. The licence is removed from this site even when the licence server cannot be reached.

Without an active licence the plugin keeps working. No update package is offered, and under an available update WordPress shows "Automatic update is unavailable for this plugin. Activate your licence to enable updates." While a licence is missing, the Plugins screen also shows a notice to administrators: "Activate your WpExperts Hub licence to receive updates for: ...". What the client sends to wpexpertshub.com, and when, is listed under Privacy.

Update information is fetched in one batched request and cached for 12 hours in the site transient wpxh_licence_check_v2. If the licence server cannot be reached, the previous answer is kept and the check is retried after one hour. If the server reports that the licence is no longer active for this site, the card changes to Not active at the next update check.

What activation creates

• Eight database tables (see Database tables), created with WordPress's dbDelta().
• Two capabilities, wphub_invoice_manage and wphub_invoice_settings, granted to Administrator (both) and, when that role exists, Shop manager (manage only). See Who can do what.
• The settings options with their defaults (one option per settings tab, plus the currency option) and the number counters for invoices, estimates and receipts.
• The daily cron event wphub_invoice_daily, first due one hour after activation.

Nothing is created for estimates until you switch them on, apart from their table and counter. No pages, posts, roles or user accounts are created.

Updating

With an active licence, update from the WordPress updates screen. You can also upload a newer zip under Plugins → Add New → Upload Plugin and choose Replace current with uploaded. On the first request after an update the plugin compares the stored plugin and database versions with its own and, when they differ, re-runs the table definitions, capability grants, default settings and the cron schedule. Existing settings and documents are kept.

Version 1.1.0 renamed the plugin's internal names (tables, options, capabilities, the cron event, admin page URLs, hooks and CSS classes). On a site that still holds data from 1.0.0, the plugin moves that data to the new names once, automatically. Old admin page URLs are redirected (HTTP 301) and client links and webhook URLs that were already sent keep working. Hooks and filters were not given aliases.

Multisite

The plugin has no network settings. The schema routine runs per site on init, so each site gets its own tables, options and capabilities the first time a request reaches it with the plugin active. Deleting the plugin runs the uninstall routine for every site of the network.

4. Quick start

1. Activate the plugin. Open Invoices → Settings → Company, enter your company name and address and choose a logo.
2. On the Currency tab tick the currencies you need and choose one default.
3. On the Invoice tab set the number prefix, starting number, "Due in (days)", default payment terms and footer. On General choose the default invoice design and click Preview under a design to see a sample PDF with your own details.
4. Open Invoices → Add New. Fill in the customer, add items, then click Save Draft.
5. Click Preview to check the PDF. Click Send Invoice to email it with the PDF attached; a draft becomes Sent.
6. When the customer pays by bank transfer or cash, open the invoice and use Payments → Record a payment. The status and the balance follow.
7. To take card payments, open Payments in Settings, switch on Online payments, enable Stripe and/or PayPal, enter the keys and add the webhook URLs shown there in the gateway's dashboard. Make a test payment first.
8. With WooCommerce, open the WooCommerce tab to attach the invoice PDF to order emails or to create an invoice for every order.

5. Features

Invoices and estimates

The plugin manages two kinds of document. They share the editor, the PDF designs, the client page and the email routine, but they have their own database tables, number sequences, statuses, list screens and settings tab.

Switching estimates on or off off by default

Open Invoices → Settings → General and tick Enable estimates (quotes) in the Estimates row. While estimates are off:

• The Estimates menu, the Estimate settings tab, the default estimate design row and the estimate subject and body fields on the Email tab are not shown, and the Payments tab describes client pages for invoices only.
• The estimate list and editor pages are not registered, so WordPress answers their old URLs with "Sorry, you are not allowed to access this page." The estimate actions (download, preview, duplicate, delete, convert, regenerate link, design preview, saving) stop with "Estimates are switched off. Turn them on in Invoices → Settings → General." Estimate client links answer "This page is not available", which also closes the PDF download and the Accept and Decline buttons for them. Sending an estimate by email is refused with "Estimates are switched off." The daily job leaves estimates alone.
• Nothing is deleted. Existing estimates, the estimate email wording and the estimate design choice come back when you switch estimates on again. The row shows how many estimates are being kept.

Sites that already had estimates when they updated to 1.1.0 start with estimates off as well; there is no migration.

The editor

Open Invoices → Add New, or click a number in the list. The page title is "Create Invoice" for a new document and "Edit Invoice INV-000001" for a saved one. The same screen with estimate wording edits estimates.

Top bar

A badge reading "Unsaved changes" appears as soon as you edit anything, and the browser warns before you leave the page with unsaved changes. If a save fails validation, nothing is lost: the values you typed are kept for five minutes and shown again with the error message.

Details

Customer

Choose Manual customer and type the details, or, when WooCommerce is active, WooCommerce customer and search. The search box needs at least two characters and returns up to 20 matches, found by WooCommerce's own customer search and also by billing first name, last name, company and email. Selecting a customer fills the fields below and records the WooCommerce user ID; every field stays editable. If the customer has a shipping address, a link Use the customer's shipping address instead appears and copies it into the same fields.

The document keeps its own copy of these details. Changing the customer's WooCommerce profile later does not change existing documents. On the PDF the company name is the first line when a company is given, with the person's name under it.

Items

Each row has a description, an SKU or reference, a quantity (hours in hourly mode), a unit price (hourly rate), a discount, a tax percentage and a calculated total. Drag the handle to reorder rows, use the copy icon to duplicate a row and the bin icon to remove it (removing the last row clears it instead). With WooCommerce active, Add a WooCommerce product searches products and variations by name or SKU (two characters or more, up to 15 hits; variable parents are skipped because their variations are listed) and adds a row with the product name, SKU and price. Only published and private products are offered.

A value that is not a number gives "Item N contains a value that is not a number." Type amounts with a full stop as the decimal separator and no thousands separator; a comma is not accepted.

Totals, notes and terms

• Discount: choose Fixed amount or Percent and a value (not negative; a percentage cannot exceed 100).
• Shipping / other charges: an optional label (up to 100 characters, printed on the PDF; "Shipping" when blank), an amount (not negative) and its own tax percentage (0 to 100).
• The tax line uses your Tax label setting. Totals update live in the browser, and are recalculated on the server when you save, preview or generate the PDF: "Totals are recalculated on the server when you save, preview or generate the PDF."
• Notes (up to 5,000 characters), Payment terms (invoices, up to 1,000) or Terms (estimates, up to 5,000), and Footer text (up to 2,000). A new document starts with the defaults from the Invoice or Estimate tab.

Sidebar

• Status: any status of that document type. Choosing Paid or Partially Paid by hand changes the status only; it does not create a payment (see Statuses).
• Currency: the enabled currencies, plus the document's own currency if it was disabled later. Amounts are not converted: "Amounts are not converted when you change the currency." Saving a currency that is disabled, other than the one the document already uses, fails with "The selected currency is not enabled."
• Pricing mode: Qty × price or Hourly. In hourly mode the columns read Hours and Hourly rate and the maths is hours × rate, but the PDF shows only the description and the amount. Hours and rate are never printed.
• PDF design: five cards with thumbnails.
• Links: Download PDF, Duplicate, Delete (with a confirmation) and, on estimates, Convert to Invoice.

Below those, saved documents show a Client page card, a Payments card (invoices), a Related box, the Email history (last 20 attempts) and the History (last 30 events).

How totals are calculated

The maths is the same on the server (which decides) and in the browser (which previews):

1. Line gross = quantity × unit price. Line net = gross − the line discount (never more than a positive gross).
2. Subtotal = the sum of the line nets.
3. The document discount (a fixed amount, or a percentage of the subtotal) is capped at the subtotal and shared across the lines with a positive net, in proportion to their net amounts. The last such line takes the rounding remainder, so the shares always add up exactly.
4. Line tax = (line net − its share of the discount) × the line's tax rate. Shipping carries its own tax rate.
5. Total = subtotal − document discount + shipping + all tax.

Every step is rounded to the currency's number of decimals (0 to 4), half away from zero. The rounding writes the value with ten decimals and lets the next digit decide, so older and newer PHP versions (PHP's own round() changed in 8.4) and the browser's JavaScript give the same last digit. The PDF lists tax as one line per distinct rate, for example "Tax (10%)", using your tax label.

Numbering

Invoices, estimates and receipts have independent sequences. A number is the prefix, then the counter padded with zeros to the chosen width: prefix INV-, padding 6 and counter 42 give INV-000042. A counter longer than the padding is not truncated.

• Claiming: the next number is taken with a single atomic update of the counter row, before the document is written, and the unique index on the document number is the final guard. If a number collides (for example one typed by hand elsewhere), the plugin claims the next one and tries again, up to 15 attempts in all. A save that fails after the number was claimed leaves a gap in the sequence.
• Starting number: saving the Invoice or Estimate tab raises the counter to the starting number if it is lower. Lowering the setting never lowers the counter, and existing numbers are not changed.
• Next number: the settings tab and the editor show the next number without using it. The preview skips numbers that already exist (it looks ahead up to 50).
• Editable numbers (off by default): with Editable invoice numbers or Editable estimate numbers ticked, the number field in the editor can be changed. A number you type must start with a letter or digit, contain only letters, digits, spaces and the characters - _ / # . and be at most 63 characters, and it must be unused: "That number is already used by another document." A number equal to the one suggested when the page opened (the form carries it in a hidden field, suggested_number) is treated as automatic and claimed fresh, so two people creating documents at the same time never collide.
• Receipts use their own counter starting at 1, with the prefix and padding from the Payments tab (default RCT-000001). One receipt number is claimed for every payment that is recorded.
• Duplicates and converted estimates always receive a fresh automatic number.

Allowed prefix characters are letters, digits and - _ / # ., up to 16 characters; any other character you type is dropped. The PDF file name is the number with spaces and slashes replaced by hyphens, and with other special characters such as # removed (WordPress's sanitize_file_name()), for example INV-000042.pdf.

Statuses

Invoice statuses

The ledger decides Paid and Partially Paid every time a payment is recorded, changed or deleted, and again after you edit an invoice that has payments (for example to change its total), unless that same save changed the status on purpose. When the net amount falls to zero, a Paid or Partially Paid invoice goes back to Sent. Cancelled, Refunded and zero-total invoices are never changed by the ledger.

Estimate statuses

PDF designs

Five designs are available for invoices and for estimates. The design is stored on each document; new documents use the default from Invoices → Settings → General. Changing the default does not change existing documents. Documents created from WooCommerce orders use the design on the WooCommerce tab, and the PDF on order emails always renders with that tab's design whatever is stored.

What every design shares:

• Page and font: A4 portrait (filter wphub_invoice_paper_size), UTF-8, DejaVu Sans, which includes the rupee, euro, pound and yen signs. "Page X of Y" is drawn at the bottom right of every page in small grey type.
• Long documents: the table header repeats on every page and rows are not split across pages.
• Footer: your document footer text is fixed at the bottom of every page. When it is empty, designs 1 to 4 print the company name instead.
• Logo: the Media Library image chosen under Settings → Company is embedded as data, with no remote request. Only JPEG, PNG and GIF files are used; any other image type prints no logo. A file larger than 1.5 MB is replaced by its "large" size when WordPress made one.
• Columns: SKU, Discount and Tax columns appear only when at least one row has an SKU, a discount or a tax rate (design 5 prints the SKU under the description). In hourly mode the Qty and Unit price columns are hidden.
• Totals: Subtotal; Discount (with its percentage when the discount is a percentage); the shipping line; one tax line per rate; then "Total due" (invoices) or "Estimate total". When payments exist, "Amount paid" and "Balance due" follow. Designs 4 and 5 label the total "Total", list "Amount paid" and end with "Amount due" (the balance) instead of "Balance due".
• Status marks: a Paid invoice carries a PAID mark in the style of the design. A Cancelled or Refunded invoice gets a "Status" row in the details block; designs 4 and 5 show 0 as the amount due, design 4's headline reads "<amount> – Cancelled" (or Refunded) and design 2's pill names the status.
• Estimates: all five designs end with "Accepted by", "Signature" and "Date" lines. Classic and Compact use teal for estimates and navy for invoices.

To see a design before you have any document, open Invoices → Settings → General and click Preview under a design card. A sample PDF opens in a new tab, using your real company details and logo with a built-in sample customer and sample items, and the default currency; the status is Sent, so Paid and partly paid variants are not shown. Nothing is saved and the number printed is only the next number, not used. The WooCommerce tab design picker has the same links.

Developers can replace a design's template from a theme or filter the data it receives, see Template files.

Where PDFs are written and who can reach them

The plugin never keeps invoice, estimate or receipt PDFs. A PDF is generated when it is asked for and streamed straight to the browser.

The temporary directory is the one WordPress 7.1.2 chooses with get_temp_dir(): the constant WP_TEMP_DIR when defined, otherwise the system temporary directory, then PHP's upload_tmp_dir, then the wp-content folder, then /tmp/. On a server where the system temporary directory is not writable, WordPress falls back to wp-content, which is inside the web root; define WP_TEMP_DIR to a folder outside it if that applies to you. Dompdf is told to use the same directory for its own working files.

The only other file the plugin writes is Dompdf's font cache in wp-content/uploads/wphub-advance-invoice/fonts (created the first time a PDF is rendered, with an index.php guard file in it and in its parent folder). It holds no customer data and is removed when the plugin's data is deleted on uninstall.

If the PDF library or a PHP extension is missing, documents still save; preview, download and email fail with the PDF engine's message ("PDF generation needs the PHP extension(s): dom, mbstring. Ask your host to enable them." or "The bundled Dompdf library is missing (vendor/ folder). Reinstall the plugin.") and a failed email is logged. "PDF generation is unavailable." is the heading of the warning shown on the plugin screens.

Emailing documents

Click Send Invoice (or Send Estimate) in the editor, or Send email under a number in the list, which opens the editor with the dialog already open. The dialog is titled "Send Invoice by email" and says "The PDF is generated and attached automatically."

Subject and message are prefilled from the templates on the Email tab with the variables replaced for this document. You can edit them each time. If the template contains neither {view_link} nor {pay_link} and client pages are on, the dialog appends a line: "View and pay online: …" for an invoice when online payments are on, "View online: …" for an invoice otherwise, and "View and respond online: …" for an estimate. The saved template is not changed.

What is sent

• The message goes through wp_mail() with the content type HTML, so your SMTP or mail-log plugin sees an ordinary WordPress email. The PDF (named like INV-000042.pdf) is the only attachment.
• Headers: From: is the Email tab's From name and From email when the address is valid (quotes, angle brackets and line breaks are removed from the name), and Reply-To: is added when set. Otherwise WordPress's defaults apply. The filter wphub_invoice_email_headers can change them.
• A successful send adds "Emailed to …" to the history and a row to the email history, and a Draft becomes Sent ("Status changed to Sent after emailing the document."). The dialog says "Email sent." and the page reloads.
• A failed send shows the reason in the dialog (the message from wp_mail_failed, or "WordPress could not send the email."), adds a "Failed" row with the reason to the email history and "Email to … failed." to the history. The status is not changed.

Variables

A variable that is not in the list is left as typed.

The client page

Every invoice and estimate has a private page at https://your-site/?wphub_invoice_doc=TOKEN. The token is i_ (invoice) or e_ (estimate) followed by 48 hexadecimal characters from 24 random bytes. It is created with the document. Customers never log in: the token in the link is the access right. The editor's Client page card shows the link with Copy, Open client page and Regenerate link.

What the customer sees

• Your logo (or company name), the document title and number, a status pill and the amount due (or "Total paid" or "Total" for a settled invoice, "Estimate total" for an estimate) with the due date or valid-until date.
• Your details, the customer's details and the document details.
• For invoices that can be paid: a Pay online card (see Online payments).
• For a Sent estimate that has not expired: Accept this estimate and Decline. After the answer, the page cannot be answered again. An expired estimate shows "This estimate has expired. Please ask for an updated one."
• The items, totals, payment terms or terms, and notes. The document footer text is not shown on the page, only on the PDF.
• For invoices with payments: a Payments table with each receipt number as a download link.
• Download PDF and Print buttons. The print style hides the buttons and the pay card.

Rules and protections

• Switch client pages off under Settings → Payments → Client pages (default on). Then every link answers "This page is not available", the {view_link} variable is empty and the WooCommerce "Download invoice" button is not offered.
• A draft answers 404 to visitors. People who can manage invoices see it, so you can preview a draft's page. A wrong, malformed or replaced token also answers 404 with the same neutral page ("This page is not available. The link may have expired or been replaced. Please contact the sender for a new one."), which reveals nothing about whether a token ever existed.
• Every response carries noindex in a meta tag and in an X-Robots-Tag header, Referrer-Policy: no-referrer, X-Frame-Options: DENY (the page cannot be shown in a frame) and no-cache headers. The plugin also defines DONOTCACHEPAGE so page-cache plugins that honour it skip the page. Your theme is not used: the page is standalone HTML with inline styles and makes no external requests, and the plugin sets no cookies.
• The Pay, Accept and Decline buttons post a WordPress nonce that contains the document's token. For a visitor who is not logged in, a WordPress nonce in WordPress 7.1.2 lasts between 12 and 24 hours and is not tied to a user, so it protects against forged requests and stale pages, not against someone who holds the link. An expired form shows "This page has expired. Please reload it and try again."
• Estimates can be answered only while their status is Sent, and the owner is emailed (when Notify me is on). The history records "Accepted by the customer on the client page." or "Declined by the customer on the client page."

Online payments (Stripe and PayPal) off by default

Customers pay on Stripe's or PayPal's own hosted page. The plugin has no card fields and never sees card details. Nothing is offered until you switch on Online payments and configure at least one gateway.

Set up Stripe

1. Open Invoices → Settings → Payments. Tick Online payments ("Show a Pay button on invoice client pages") and Enable Stripe.
2. Paste your Secret key. It must look like sk_test_… or sk_live_… (a restricted key rk_test_… or rk_live_… with Checkout Sessions write access also works). Publishable keys (pk_…) are not accepted. A TEST or LIVE badge appears next to the Stripe heading once the key is accepted; the mode comes from the key's prefix.
3. In the Stripe dashboard (Developers → Webhooks) add the endpoint shown in Stripe webhook URL and select the events checkout.session.completed, checkout.session.async_payment_succeeded and charge.refunded. Paste the endpoint's signing secret (whsec_…) into Webhook signing secret.
4. Make a payment with test keys before you switch to live keys.

Set up PayPal

1. On the same tab tick Enable PayPal. Sandbox mode is on by default: leave it on while testing with sandbox credentials and switch it off with your live credentials. A SANDBOX or LIVE badge shows once PayPal is enabled and has a client ID and a secret.
2. Enter the Client ID and the Client secret from the PayPal Developer dashboard (Apps & Credentials).
3. Optional but recommended: create a webhook in PayPal with the URL shown under PayPal webhook URL, subscribe it to PAYMENT.CAPTURE.COMPLETED and PAYMENT.CAPTURE.REFUNDED, and enter its Webhook ID. Without a Webhook ID every PayPal notification is rejected; payments are then recorded only when the customer comes back to your site.

The secret fields never show the saved value. A saved field shows "•••••••••••• (saved – leave empty to keep)" and a "✓ Saved" mark; leaving it empty keeps the stored value. There is no button to erase a saved secret: type a new one, or untick the gateway's Enable box.

What the customer experiences

1. The customer opens the invoice link. If the invoice can be paid, a Pay online card offers one button per available gateway: "Pay with Card (Stripe)" and "Pay with PayPal". The card is shown when the status is not Draft, Paid, Cancelled or Refunded, a balance remains, Online payments is on, and at least one gateway is enabled and configured.
2. When partial payments are allowed and the balance is above the smallest partial payment, the customer chooses "Pay the full balance (…)" or "Pay a different amount" and types an amount (digits with an optional decimal point and up to four decimals).
3. The plugin checks the amount and starts the checkout. Stripe receives a Checkout Session for one line item named "Invoice INV-000042 – Your Company" for the amount in the invoice currency, with the customer's email prefilled when it is valid. PayPal receives an order with intent CAPTURE, no shipping address and the button text "Pay Now". The history records "The customer started an online payment of … with …."
4. The customer pays on the gateway's page and returns to the invoice. The plugin checks the payment with the gateway itself (it fetches the Stripe session with your secret key, or captures the approved PayPal order) and never trusts the address in the browser. It then records the payment in the ledger.
5. The page says "Thank you! Your payment was received. A receipt is available below." If the gateway has not finished (PayPal "pending", an asynchronous Stripe method) it says "Your payment is being processed. You will receive a receipt as soon as it is confirmed."; the webhook records the payment when it arrives. If the customer cancels, "The payment was cancelled. You have not been charged."

Rules for the amount

• The amount cannot exceed the balance: "The amount cannot be more than the balance due (…)."
• A partial amount needs Partial payments on: "Please pay the full balance." It must also be at least the smaller of the balance and Smallest partial payment (default 1): "The smallest partial payment is …." The balance itself is always payable, so the last payment may be smaller than the minimum.
• Stripe and PayPal apply their own minimum charge amounts. The plugin does not know them; the gateway rejects the request, the history records the gateway's message under "payment failed", and the customer sees "The payment could not be started. Please try again in a moment or contact us."

How a payment is recorded safely

• A payment is only ever recorded from the gateway's own confirmation (the verified return, or a signed webhook), from an administrator or, with the WooCommerce options on, from a paid WooCommerce order.
• Both paths can fire for the same payment. The ledger has a unique key on gateway plus transaction ID, so a repeated or parallel delivery returns the existing row and counts nothing twice.
• Stripe webhooks are authenticated by the Stripe-Signature header: an HMAC-SHA-256 of the timestamp and the raw body with your signing secret, compared in constant time, with a tolerance of 300 seconds either way. With no signing secret saved, nothing is accepted. PayPal webhooks are verified by calling PayPal's own verification endpoint with your Webhook ID.
• The webhook endpoint (?wphub_invoice_webhook=stripe or =paypal) accepts only POST requests up to 1 MB (a larger body gets the "Unknown gateway" answer) and answers JSON with a status and a short message, for example "Recorded", "Already recorded", "Invalid signature" (HTTP 400), "POST only" (405) or "Unknown gateway" (404).
• A payment whose currency differs from the invoice's currency is refused ("The payment currency does not match the invoice currency.").
• The plugin never issues a refund. Refunds you make in Stripe or PayPal reach the invoice through the webhooks (see The payment ledger).

The gateway API requests use the WordPress HTTP API with a 25-second timeout and the user agent WPHubAdvanceInvoice/1.1.1; https://your-site. Which wallets and card brands appear is decided by your Stripe or PayPal account; the plugin does not choose payment method types. The Settings labels read "Accept cards, Apple Pay and Google Pay with Stripe Checkout" and "Accept PayPal (and cards through PayPal)".

The payment ledger and partial payments

The Payments card in the invoice editor is the single source of truth for money. It shows Paid and Balance due, and one entry per payment: the amount, the method and date, the note, "Refunded …" when part of it was refunded, a link with the receipt number that downloads the receipt PDF, and a bin icon that deletes the payment.

Record a payment by hand

Open Record a payment in the card (bank transfer, cash, cheque and so on).

Recording a payment claims a receipt number, writes the history line "Payment of … received (…). Receipt …." and recalculates the invoice. The message is "Payment recorded."

How the invoice follows the ledger

• Net paid is the sum of each completed payment minus what was refunded on it. The balance is the total minus net paid, never below zero.
• Net paid at or above the total (less half of the currency's smallest unit) makes the invoice Paid; above zero but below the total makes it Partially Paid; back to zero returns a Paid or Partially Paid invoice to Sent.
• Deleting a payment ("The payment was deleted and the invoice recalculated.") makes no call to Stripe or PayPal. Use it only to correct a wrong manual entry. A deleted payment's receipt number is not reused.
• Refunds made in Stripe (charge.refunded) or PayPal (PAYMENT.CAPTURE.REFUNDED or PAYMENT.CAPTURE.REVERSED) are written to the payment as "Refunded …" and the status follows: a fully paid invoice with a refund becomes Partially Paid. A refund can never exceed the payment.
• The invoice list shows "Balance …" under the amount of a part-paid invoice. The client page and the PDF show the paid amount and the balance.
• Deleting an invoice also deletes its payments.

Receipts

Every payment gets a numbered PDF receipt (default RCT-000001). The receipt uses the Minimal look and has no design choice. It shows the receipt number, the invoice number, the date paid, From and Bill to, the headline "<amount> paid on <date>", the items and totals with the amount paid, a payment history table with this payment highlighted (refunds are marked) and, while a balance remains, "Balance remaining".

• Admin: click the receipt number in the ledger.
• Customer: the receipt number in the Payments table of the client page.
• Email: with Email receipts on, the customer gets the receipt as an attachment after each payment, using the Receipt email subject and message. It goes to the payer's email from the gateway when valid, otherwise to the customer's email on the invoice. With no valid address nothing is sent and nothing is logged. The attempt, success or failure, is added to the email history.
• Payments recorded from a WooCommerce order (see PDF on order emails) never send a receipt email; WooCommerce has its own emails.

When a payment arrives through Stripe or PayPal and Notify me is on, you also receive a plain-text email, "Payment received: … for invoice …", with the customer, amount, method, receipt number, balance and a link to the invoice. It goes to the company email under Settings → Company, or to the site admin email when that is not valid. Manual payments and WooCommerce payments do not send it.

Estimates, accepting and converting

With estimates switched on, the Estimates menu works like the invoice screens. Send an estimate, and the customer can Accept this estimate or Decline on the client page. You are emailed when Notify me is on ("Estimate EST-000001 was accepted" or "declined", with the total and a link). Neither answer converts anything automatically.

Convert to Invoice (a button in the editor sidebar and a link in the list) creates a new draft invoice and leaves the estimate's content untouched:

• Copied: customer and WooCommerce customer link, currency (even if that currency has been disabled since), pricing mode, reference, discount, shipping, notes and all items.
• Fresh or from settings: a new invoice number, today as the invoice date, the due date from "Due in (days)", the payment terms and footer from the Invoice tab and the default invoice design. The estimate's terms are not copied.
• The estimate gets the status Converted and a link to the new invoice. The invoice gets a link back and the history line "Created from estimate …". Each shows the other in its Related box (the invoice's box shows the estimate while estimates are on).
• Converting an estimate that is already Converted asks "This estimate was already converted. Create another invoice from it?" and makes another invoice.
• Deleting either document clears the link on the other.

Currencies

Seven currencies are built in: US Dollar, Euro, British Pound, Indian Rupee, Australian Dollar, Canadian Dollar and Japanese Yen. Enable the ones you need and choose one default under Invoices → Settings → Currency (see the Currency tab). Every document can use any enabled currency. A currency only changes how amounts are displayed and rounded; nothing is converted. An existing document keeps working with a currency that you disable later. The filter wphub_invoice_currency_definitions adds more.

The invoice and estimate lists

Open Invoices → All Invoices (or Estimates → All Estimates). Until the first document exists the screen shows "Create your first invoice" with an Add new invoice button and, for people who can change settings, a link "First, add your company details and logo".

Summary tiles

Above the list, four tiles show the number of documents and the amounts per currency (largest first, up to three currencies, then "+N more"). A tile with a single status links to the list filtered on it. The tiles add up each document's total: a Partially Paid invoice counts at its full total, not at its balance.

Columns, search, filters and sorting

• Columns (invoices): Invoice (the number, with row actions), Customer (with the company underneath), Date, Due date, Amount (with "Balance …" under a part-paid invoice), Currency, Status, WooCommerce order (a link to the order), PDF (a button) and Email ("Not sent", or "Sent N times, last …"). Estimates show Valid until instead of Due date and Converted invoice instead of WooCommerce order.
• Row actions: Edit, Preview (the PDF in a new tab), Download PDF, Send email, Duplicate, Delete (with a confirmation), and on estimates Convert to invoice.
• Status views above the table show All and each status that has documents, with counts.
• Search ("Search invoices"): matches part of the number, customer name, company, email and reference, and for invoices also the WooCommerce order number and the purchase order number.
• Filters: a currency drop-down ("All currencies"), a month drop-down ("All dates", the last 36 months that have documents, by invoice date) and a Filter button.
• Sorting: click Invoice, Customer, Date, Due date, Amount, Currency or Status. The default order is newest first. The list shows 20 documents per page; this is not a setting.

Bulk actions

Tick rows and choose Delete or Mark as … followed by any status of that type, then Apply. Messages: "N documents deleted.", "N documents updated." and, when no row is ticked, "Select at least one document." "Mark as" changes the status only. It creates no payment, sends no email and does not touch the ledger (so "Mark as Paid" does not record a payment). Each change is written to the history.

Duplicate creates a new draft with a new number and today's date, copies the customer, items, amounts, reference, notes, terms, footer and design, recalculates the due date or validity date from your settings, and does not copy payments, the WooCommerce order link or the estimate link. If the document's currency has been disabled since, the duplicate is refused with "The selected currency is not enabled." and you land on the list; enable the currency again first.

History and email log

Every saved document shows two logs in the editor sidebar. History (the latest 30 events) records who did what and when: created, updated, status changes (with the old and new status, and a reason for automatic ones), PDF downloaded, emailed or email failed, link regenerated, payment started, payment failed (with the gateway's message, visible only to you), payment received, payment deleted, refund recorded, converted, duplicated, and WooCommerce events such as "Created automatically from WooCommerce order #N." and "WooCommerce refund #R (…) added as a credit line." Automatic events are attributed to no user. Email history (the latest 20 attempts) lists each recipient, date and subject, "Sent" or "Failed" and the error.

Both logs belong to the document. They are deleted with it and are not pruned otherwise; there is no retention setting.

WooCommerce integration

WooCommerce is optional. The plugin treats it as active when the WooCommerce class and the wc_get_order() and WC() functions exist. Orders and products are only read. An invoice stores its own copy of the order's data and never depends on the product again. The only things written to a WooCommerce order are optional private order notes (see Order notes and logs).

If you deactivate WooCommerce later, automatic invoices, email attachments and the order-screen features stop, and the list shows an order link as plain text ("#1234"). Invoices that came from orders are kept.

Customers, products and importing an order

In the invoice editor, Create from a WooCommerce order searches orders by number (digits, with or without a leading #), customer name or email. One character is enough; up to 15 results show as "#number – customer – date – status – total". Choosing one (and confirming "Importing replaces the current items. Continue?" when the items are not empty) fills the form. The order is not changed, and nothing is saved until you click Save.

• Customer: billing name, company, phone, address (country and state codes are turned into names), email and the WooCommerce customer ID. A guest order becomes a manual customer; a registered customer becomes a WooCommerce customer. If the billing name and company are empty, the shipping name is used. The shipping address is offered through Use the customer's shipping address instead.
• Items: one row per product line, with the product name and its chosen variation attributes on following lines, the SKU, quantity, unit price = line subtotal ÷ quantity, discount = subtotal − total, and tax rate = the line's tax ÷ its total × 100. Fees become rows of quantity 1.
• Shipping: taken from the order's shipping lines (label, amount, and the rate derived from its tax).
• Other fields: the invoice date is the order date, the due date is that date plus "Due in (days)", the reference is "Order #N", the notes come from the Invoice tab, the pricing mode is Qty × price, and the order total, date and currency are remembered with the invoice. The order link shows as "WooCommerce Order #N → Invoice …".
• Currency: the order's currency when it is enabled in Settings → Currency. Otherwise the default currency is used and a warning explains that the amounts were imported unchanged.
• Warnings shown above the form: the order uses a currency that is not enabled; "The invoice total (…) differs from the WooCommerce order total (…)", usually tax rounding or refunds; and "An invoice already exists for this order: …."

Tax rates are derived from the order's tax amounts, so a total can differ from the order by a cent; the warning tells you when it does. The search results and the data returned are only available to users with the manage capability.

Invoice PDF on WooCommerce order emails off by default

Open Invoices → Settings → WooCommerce and tick Auto attach ("Attach the invoice (PDF) to WooCommerce order emails"). Choose the Design template and tick the emails that should carry the PDF: Order on-hold, Processing order (ticked by default), Completed order (ticked by default) and Customer invoice / order details. Whether an email is sent at all remains a WooCommerce setting under WooCommerce → Settings → Emails.

• The plugin hooks WooCommerce's woocommerce_email_attachments filter at priority 20. It adds a PDF only for the ticked customer emails, only when the email's object is a real shop order (never for admin emails such as New order, and never for a WooCommerce Subscriptions object).
• One order, one invoice. The first time an email needs it, the invoice is created from the order and takes the next invoice number, even when "Auto record orders" is off. Every later email of that order carries the same invoice. A hand-made invoice linked to the order is reused. Two emails sent at the same moment (Processing and Completed, say) cannot make two invoices: a database lock per order makes the second wait.
• The invoice is created with the status Sent, the invoice date set to the order date and a due date of that date plus "Due in (days)". An order on hold keeps its due date. The document is attributed to no user (the shopper who happens to be checking out is not recorded).
• The PDF always renders with the design chosen on this tab (the stored design is not rewritten), so changing the setting changes every later email. A theme override of the design template applies as everywhere.
• When Paid orders is on (default) and the order is paid, the order's payment is recorded on the invoice with no receipt email, so the PDF says PAID instead of showing a due date. "Paid" here means the order status is Processing or Completed, WooCommerce's default list of paid statuses in WooCommerce 11.1.2, which stores can change with the filter woocommerce_order_is_paid_statuses. An invoice made while the order was on hold turns Paid when the order becomes paid.
• Free orders (default on): orders with a total of zero get no invoice and no attachment.
• If the PDF cannot be built (no PDF library, say) the email is still sent and the order gets a private note "The invoice PDF could not be attached to the email: …".
• The temporary PDF is deleted when the request ends. A mail-queue plugin that sends after the request has ended needs the filter wphub_invoice_wc_keep_attachments returning true; the files then stay until the daily clean-up (older than 24 hours).

Filters let you veto a single order, for example by payment method: wphub_invoice_wc_attach_invoice for the attachment and wphub_invoice_wc_record_invoice for automatic recording (see Hooks).

Orders as invoices (automatic records) off by default

Tick Auto record orders ("Create an invoice automatically for every WooCommerce order") and choose Create it when the order is: any WooCommerce order status except Cancelled, Failed, Refunded and the draft statuses (statuses added by other plugins are listed too). Processing and Completed are ticked by default. If you tick none, saving shows a warning and no invoice is created.

• The invoice is created the moment the order reaches a ticked status, once per order, with the next invoice number and the design from the tab. It appears under Invoices like any other. "Pending payment" and "On hold" create an invoice with a due date; "Processing" and "Completed" mean the customer has paid, so with Paid orders on the invoice is marked Paid.
• Orders that already have an invoice, made by hand or earlier, are left alone. Zero-total orders are skipped while Free orders is on. An order created in code can reach its status before its total is calculated, so an order skipped for a zero total is looked at again once when the request ends.
• An order that becomes paid after its invoice was made (for example on hold, then Processing) has the payment recorded on the existing invoice. This never creates an invoice by itself.
• The reference is "Order #N" (see the subscription format below), the history reads "Created automatically from WooCommerce order #N.", and the order gets a note "Invoice X created from this order." Any import warnings are added to a second note.
• Errors in any of this are caught, written to the WooCommerce log and noted on the order; they never stop a checkout or a status change.

Cancellations, refunds and subscriptions

These three switches only act while Auto record orders is on. Cancelled orders and Refunds act only on orders that already have an invoice; Subscriptions decides whether subscription orders are invoiced at all. All three are on by default (they stay hidden until Auto record is ticked).

A refunded or cancelled invoice shows nothing as due on the PDF, the client page, the order box and the list.

The Invoice box on the order screen

Every WooCommerce order has an Invoice box in the sidebar (both with and without High-Performance Order Storage), for people who can manage invoices. With an invoice it shows the number (a link to the editor), the status, the total, the amount paid, the due date, Download PDF and Open invoice. The invoice shown is the newest one that is not cancelled. Without an invoice it shows "This order has no invoice yet." and Create invoice.

Create invoice makes the invoice at once and returns to the order: it ignores the status list and the free-order rule because you asked for it, uses the design from the WooCommerce tab, records the payment when the order is paid (if Paid orders is on) and attributes the invoice to you. If the order already has one, the notice says "This order already has invoice …."

Download invoice for customers off by default

Tick Customer download to show an Invoice button in My Account → Orders and a Download invoice (PDF) button on the order page (after WooCommerce's order details table). It appears only for orders that already have an invoice, never for a draft or cancelled invoice. The button is the invoice's private client link with the PDF action, so Client pages must be on in the Payments tab; otherwise no button is shown. If another invoicing plugin adds its own button, customers will see both.

Order notes and logs

Order notes (default on) adds a private note to the order when an invoice is created, attached to an email, restored, cancelled, marked refunded or updated for a refund, for example Invoice INV-000042 attached to the "Processing order" email. The same switch controls the failure notes. Errors thrown while the plugin processes an order are written to the WooCommerce log (source wphub-advance-invoice) whatever this switch says.

Other invoice plugins

This plugin adds its PDF at priority 20 and does not remove attachments added by anyone else. If you also run another plugin that attaches an invoice to the same emails, such as the free PDF Invoice for WooCommerce with its own email list ticked, customers receive two PDFs. Untick the emails in one of the two plugins. The two plugins can share one site: if the other plugin has already loaded Dompdf, this plugin reuses that copy.

Automatic tasks

One WordPress cron event, wphub_invoice_daily (daily), does three things. It is scheduled at activation (first run one hour later) and re-scheduled when the plugin upgrades its stored version; deactivating the plugin removes it.

1. Marks Sent, Pending Payment and Partially Paid invoices with a due date before today as Overdue, when Automatic status updates is on. Up to 500 invoices per run. No email is sent.
2. With estimates on and the same setting, marks Sent estimates with a valid-until date before today as Expired (up to 500 per run).
3. Deletes the plugin's temporary PDF folders that are more than 24 hours old.

The date used is today in the site's time zone. Nothing is ever marked Paid automatically by this job.

Who can do what

The plugin adds two capabilities. They are granted to roles when the plugin is activated or upgraded.

The Shop manager role exists only with WooCommerce. A role that does not exist when the capabilities are granted does not get them later; deactivate and reactivate the plugin to grant them again. The filter wphub_invoice_default_roles changes the list of roles; every role you add through it receives both capabilities, only the role named shop_manager is limited to the first. Deleting the plugin removes both capabilities from every role, even when you keep the data.

Every admin action that changes something checks the capability and a nonce bound to the action, the document type and the document ID, so a link made for another document or action is refused. The AJAX endpoints check the capability and one shared nonce. The licence screen needs manage_options. Client pages need neither (the token is the credential), and the webhooks are authenticated by signature.

6. Screens and menu paths

The menu Invoices sits at position 56 with the dashicon "media-text"; Estimates (position 57, dashicon "clipboard") appears only while estimates are on. Every plugin screen needs the capability shown. Their style sheet and scripts are loaded on these screens only.

The Settings screen is titled "Invoice settings" while estimates are off and "Invoice & Estimate settings" while they are on. The tabs run General, Company, Currency, Invoice, Estimate (only while estimates are on), Payments, WooCommerce (only when WooCommerce is active) and Email, except that the WooCommerce tab comes last when estimates are off. While you edit a saved document, the menu keeps "All Invoices" (or "All Estimates") highlighted. Admin notices ("Saved.", "Settings saved.") are queued for your next plugin screen, or for the next admin screen of any kind when the action started on the WooCommerce order screen.

When the PDF library is unavailable, a warning "PDF generation is unavailable." with the reason is shown on every plugin screen.

7. Settings

Open Invoices → Settings. Each tab is its own form and is stored in its own option, so saving one tab never changes another. After saving you see "Settings saved." or, when the plugin adjusted something, "Settings saved, with changes:" followed by the reasons. Only users with wphub_invoice_settings can open the screen. Fields that are missing from a stored option fall back to the defaults shown here.

General

Option wphub_invoice_general.

Company

Option wphub_invoice_company. These details are printed on every PDF and client page. The filter wphub_invoice_company can adjust them. Text fields are cleaned with WordPress's text-field sanitiser; there is no length limit beyond what the database stores.

Currency

Option wphub_invoice_currencies: the default code and, per currency, enabled, symbol, position, decimals, decimal_sep and thousand_sep. The table lists the seven built-in currencies with a live preview of 1234567.891 in each row.

Rules, enforced when you save and in the browser while you edit:

• At least one currency must stay enabled; otherwise your previous selection is kept ("At least one currency must stay enabled. Your previous selection was kept.").
• Exactly one currency is the default and it must be enabled. Choosing a default enables it. A default that is not enabled is reset ("The default currency must be one of the enabled currencies. It was reset.").
• The decimal and thousands separators must differ; if they do not, the thousands separator is changed ("…: the decimal and thousands separators must differ; the thousands separator was changed.").
• At first activation, USD, EUR, GBP and INR are enabled; the default is the WooCommerce store currency when WooCommerce is active and the currency is one of the seven (it is enabled too), otherwise USD.

Invoice

Option wphub_invoice_invoice.

Estimate

Option wphub_invoice_estimate. This tab exists only while estimates are on.

Payments

Option wphub_invoice_payments. See The client page and Online payments for how these work together.

The Stripe and PayPal keys are stored in this option in the database like any other plugin setting. They are never printed back into the page, never shown on a public page and never put in error messages.

WooCommerce

Option wphub_invoice_woocommerce. The tab appears only when WooCommerce is active. Rows for a section appear only while its main switch is ticked. See WooCommerce integration for what each does.

Email

Option wphub_invoice_email. Emails are sent with wp_mail(). The Variables row lists the placeholders per email type (the estimate group only while estimates are on); see Emailing documents.

Default bodies:

Invoice:
Hello {customer_name},

Please find attached invoice {invoice_number} for {invoice_total}, dated {invoice_date}. Payment is due by {due_date}.

Thank you,
{company_name}

Estimate:
Hello {customer_name},

Please find attached estimate {estimate_number} for {estimate_total}, dated {estimate_date}. It is valid until {valid_until}.

Kind regards,
{company_name}

Receipt:
Hello {customer_name},

Thank you! We received your payment of {payment_amount} on {payment_date} for invoice {invoice_number}. Your receipt is attached.

Remaining balance: {balance_due}

Kind regards,
{company_name}

Subjects are single-line text. Bodies are plain text; HTML tags are removed when you save.

8. Developer reference

The plugin registers no shortcodes, no blocks, no REST routes and no WP-CLI commands. Its extension points are the actions and filters below, template overrides, the admin-post and AJAX actions, and the gateway registry. The PHP classes (WPHub_Invoice_*) are autoloaded from includes/ and includes/admin/ and can be called from your code, but they are the plugin's own internals, not a documented API, so check any call you depend on after an update.

Hooks

Actions the plugin fires

Filters the plugin applies

Examples:

// No invoice PDF on cash-on-delivery order emails.
add_filter( 'wphub_invoice_wc_attach_invoice', function ( $attach, $order, $email_id ) {
	if ( 'cod' === $order->get_payment_method() ) {
		return false;
	}
	return $attach;
}, 10, 3 );

// Do not create automatic invoices for cash-on-delivery orders.
add_filter( 'wphub_invoice_wc_record_invoice', function ( $record, $order ) {
	return 'cod' === $order->get_payment_method() ? false : $record;
}, 10, 2 );

// Offer PayPal only for GBP and USD invoices.
add_filter( 'wphub_invoice_gateway_supports_currency', function ( $supported, $currency, $gateway_id ) {
	if ( 'paypal' === $gateway_id && ! in_array( $currency, array( 'GBP', 'USD' ), true ) ) {
		return false;
	}
	return $supported;
}, 10, 3 );

// Letter paper instead of A4 (the built-in designs are laid out for A4).
add_filter( 'wphub_invoice_paper_size', function () {
	return 'letter';
} );

// React to a recorded payment.
add_action( 'wphub_invoice_payment_recorded', function ( $payment_id, $invoice_id ) {
	$payment = WPHub_Invoice_Payments::get( $payment_id );
	error_log( sprintf( 'Invoice %d received %s via %s', $invoice_id, $payment['amount'], $payment['gateway'] ) );
}, 10, 2 );

Recording a payment from your own code

WPHub_Invoice_Payments::record( $invoice_id, $args ) adds a ledger row, claims a receipt number, recalculates the invoice and, depending on send_receipt and the Email receipts setting, emails the receipt. When send_receipt is true and the gateway is anything other than manual, it also sends you the "Payment received" email if Notify me is on. It returns array( 'id' => int, 'duplicate' => bool ) or a WP_Error. The arguments are amount (required, greater than zero), gateway (default manual), txn_id (an empty value becomes a random manual-… ID; a repeated gateway plus transaction ID returns the existing row with duplicate true), method_label, payer_email, note, paid_at (Y-m-d or Y-m-d H:i:s), currency (must equal the invoice's currency) and send_receipt (default true).

$result = WPHub_Invoice_Payments::record( 123, array(
	'amount'       => 50.00,
	'gateway'      => 'manual',
	'method_label' => 'Bank transfer',
	'paid_at'      => '2026-10-04',
	'note'         => 'Matched from the bank statement',
	'send_receipt' => false,
) );

Adding a gateway

Extend the abstract WPHub_Invoice_Gateway and add an instance with the wphub_invoice_gateways filter. You implement id(), label(), is_available() and create_payment( array $doc, $amount, array $urls ), which returns the hosted payment page address or a WP_Error. The pay form, amount validation and the gateway buttons then work for it. The built-in return handling and the webhook endpoint (?wphub_invoice_webhook=) only know stripe and paypal; your gateway must record the payment itself, for example with WPHub_Invoice_Payments::record() from its own callback.

Core and WooCommerce hooks the plugin uses

The licence client adds admin_menu, admin_init, admin_notices, pre_set_site_transient_update_plugins (adds the plugin to the update transient), plugins_api (priority 20; answers the "View details" request for this plugin's slug itself), http_request_args and http_request_host_is_external (both only relax checks for a local development licence server such as .local or .test), upgrader_process_complete (clears its cache) and in_plugin_update_message-{basename}.

Admin-post and AJAX actions

All need a logged-in user. Admin-post URLs are admin-post.php?action=…. The GET actions take type (invoice or estimate), id and _wpnonce, where the nonce action is wphub_invoice_{action}_{type}_{id}.

The AJAX actions (admin-ajax.php, logged-in only, no nopriv variants) take the field nonce (action wphub_invoice_ajax) and answer JSON with wp_send_json_success() or wp_send_json_error(). All need wphub_invoice_manage; the first four also need WooCommerce ("WooCommerce is not active." with HTTP 400 otherwise).

Front-end routes

All are on your home address and are handled by the plugin before WordPress renders a page.

Tokens must match ^[ie]_[a-f0-9]{48}$ and the prefix must match the document type. Pages from 1.0.0 that used the old parameter names keep working.

Template files

PDF templates are PHP files that receive the view model in $v and echo HTML for Dompdf. Copy a file to your theme (or child theme) to override it:

The lookup uses locate_template(), so a child theme wins over its parent. The filter wphub_invoice_template_file can then change a design's path. Dompdf supports a limited part of CSS: the bundled templates use tables for layout, no flexbox or grid, thead { display: table-header-group } for repeated headings and page-break-inside: avoid on rows. Escape everything you print.

The view model $v contains: type, is_invoice, design, hourly, currency, status, is_paid, is_finished, status_label, labels (every printed label), palette, number, company (name, legal, logo as a data URI, address lines, phone, email, website, tax_id, reg, extra lines), customer (name, contact, address lines, email, phone, tax_id), details (label and value pairs), date, date2, columns (sku, qty, price, discount, tax), items (n, description, sku, qty, unit_price, discount, tax_rate, amount), totals (label, value, type of row, total or balance), total, headline, amount_due, notes, terms, footer and page_text. The receipt template also gets receipt (number, date, amount, method, headline, history, balance, has_balance) and extra labels. Amounts are already formatted text.

Database tables

Eight tables with your WordPress prefix (shown as wp_), created with dbDelta() in the site's default character set and collation. Money columns are decimal(20,4). The schema version is stored in wphub_invoice_db_version (1.1.0).

wp_wphub_invoice_invoices and wp_wphub_invoice_estimates

Both share these columns:

Invoices add wc_order_id, wc_order_number (varchar 64), amount_paid (the net of the ledger, maintained only by the payment code), source_estimate_id, due_date, po_number and payment_terms. Estimates add converted_invoice_id, valid_until and terms. Indexes: status, issue date, the second date, customer name and email, WooCommerce customer and order, the linked ID and public_token.

Items, logs, counters and payments

Options, transients, locks and constants

The plugin stores no post meta, user meta or term meta and registers no post types, taxonomies, rewrite rules or user roles. The only WooCommerce data it writes is private order notes.

Cron events

wphub_invoice_daily (recurrence daily): overdue invoices, expired estimates and temporary-file clean-up, see Automatic tasks. To run it by hand, trigger the event with a cron tool of your choice; there is no WP-CLI command of its own.

File layout

wphub-advance-invoice/
  wphub-advance-invoice.php   main file, autoloader, licence registration
  uninstall.php               uninstall routine
  readme.txt
  includes/                   document, settings, currency, numbering, PDF, email, payments,
                              gateways, public page, WooCommerce classes
  includes/admin/             menus, editor, lists, settings screen, AJAX
  templates/pdf/              design-1.php, design-2.php, design-3.php, design-4.php,
                              design-5.php, receipt.php
  templates/public/           document.php (client page)
  assets/css, assets/js       admin.css, common.js, editor.js, settings.js
  licence/                    WpExperts Hub licence and update client
  languages/                  wphub-advance-invoice.pot (no translations bundled)
  vendor/                     bundled Dompdf 3.1.6 and its libraries (Composer)

The class loader maps WPHub_Invoice_Foo_Bar to includes/class-wphub-invoice-foo-bar.php (or the same name under includes/admin/). The text domain is wphub-advance-invoice; translations are loaded from languages/ on init.

9. Privacy

What is stored and where

• Documents (database tables wp_wphub_invoice_*): for every invoice and estimate, the customer's name, company, email, phone, address, tax or VAT number and, when chosen from WooCommerce, the WordPress user ID; the items, amounts, dates, notes and the client page token. Documents keep this snapshot until you delete them.
• Payments: amount, currency, gateway, transaction ID, receipt number, method label, a note, the payer's email address (from the gateway, or the customer's email for manual payments), the date and the ID of the user who recorded it.
• History and email history: event text, the IDs of the users who acted, the recipients, subject and failure reason of every email attempt. Failed gateway checkouts are logged with the gateway's message.
• Settings (options): your company details, email templates and, in wphub_invoice_payments, the Stripe secret key, Stripe webhook signing secret, PayPal client ID, PayPal client secret and PayPal webhook ID. WordPress has no secret store, so these sit in the options table as plain text, like any other plugin setting. They are never printed into a page, a URL or an error message. The licence key is stored the same way.
• Short-lived data: transients listed under Options, transients, locks and constants, including a PayPal access token.
• Files: no PDF is kept. A PDF written for an email attachment exists briefly in WordPress's temporary directory, in a folder named wphub-invoice- plus random characters (see Where PDFs are written). Dompdf's font cache lives in wp-content/uploads/wphub-advance-invoice/fonts.
• WooCommerce: private order notes (for example "Invoice INV-000042 attached to the "Processing order" email."). Nothing else is written to orders, products or customers.

Cookies

The plugin sets no cookies, on the client page or anywhere else. The client page does not load scripts or fonts from other sites; it contains a small inline script that shows or hides the custom amount field.

Data sent to other services

Stripe and PayPal send webhook notifications to your site. They contain payment details. The plugin stores the payer's email address from Stripe's session or webhook and from PayPal's capture response when the customer returns; it does not store one from a PayPal webhook. Customers enter card details only on the gateways' own pages. Dompdf is configured not to fetch remote files, so a PDF never triggers a request to another site.

Retention, export and erasure

• Nothing is deleted automatically except temporary PDF folders older than 24 hours and expiring transients. Documents, payments, history and email history stay until you delete the document; deleting a document removes its items, history, email history and (invoices) payments, but not WooCommerce order notes. Check your own record-keeping duties before deleting invoices.
• The plugin registers no personal-data exporter or eraser and adds no text to the privacy policy guide, so WordPress's Export Personal Data and Erase Personal Data tools do not include data held in its tables. Use the list search (by name, company, email or reference) to find a person's documents.

Deactivation and uninstall

• Deactivating removes only the daily cron event. All data, settings and capabilities stay.
• Deleting the plugin always removes the cron event and both capabilities from every role. It deletes everything else only when Delete all plugin data when the plugin is deleted and its confirmation box were both ticked under Settings → General (both are off by default). In that case it drops the eight tables; deletes the options wphub_invoice_general, _company, _invoice, _estimate, _email, _payments, _woocommerce, _currencies, _db_version and _version; deletes every transient starting wphub_invoice_; removes anything still stored under the names used by 1.0.0; and deletes the uploads/wphub-advance-invoice folder (the font cache). On multisite it does this for every site.
• Left behind even then: the licence options _wphub-advance-invoice_licence_key and _wphub-advance-invoice_key_status, the licence cache wpxh_licence_check_v2, the option wphub_invoice_legacy_done, the private notes on WooCommerce orders and any stale temporary PDF folders in the temporary directory.

10. Troubleshooting

11. FAQ

12. Changelog

1.1.1

• Fixed: the invoice editor passed the type "estimate" to its script (a page-name check left over from the 1.1.0 rename never matched), so Send Invoice, the list's Send email action and the automatic PDF download after Save & Generate PDF did nothing, and when an estimate with the same number existed the Send dialog was filled with that estimate and mailed it. Invoices and estimates now each load their own document.

1.1.0

• Changed: every internal name now uses the plugin's real name instead of a two-letter abbreviation: admin page URLs (wphub-invoices, wphub-estimates, wphub-invoice-settings), database tables (wp_wphub_invoice_*), options, hooks and filters (wphub_invoice_*), classes and CSS classes. Existing data is moved automatically on update, old admin URLs redirect, and client links and webhook URLs that were already sent keep working
• New: Settings → General → Estimates switch (off by default): the Estimates menu, settings tab, emails, client-page Accept / Decline and the daily expiry job only exist while it is on; nothing is deleted when it is off
• Fixed: previewing the unsaved form of an existing estimate no longer logs a PHP warning
• New: Settings → WooCommerce tab: auto attach the invoice PDF to WooCommerce order emails (choose the design and the emails), auto record WooCommerce orders as invoices at the order statuses you pick (paid orders show as Paid, free orders can be skipped), an Invoice box with a Create invoice button on every order, an optional Download invoice button in My Account, and switchable private order notes
• New: with Auto record orders on, a cancelled order cancels its invoice (restored with the order), refunds add a credit line and keep a paid invoice Paid, a fully refunded order marks the invoice Refunded (new status), and WooCommerce Subscriptions orders are invoiced with the subscription named on them
• Changed: nothing is shown as due on a cancelled or refunded invoice (PDF, client page, order box, list)
• Fixed: notices queued by an action that lands on a non-plugin screen (the order screen) are shown there instead of waiting for the next invoice page
• New: private client page for every invoice and estimate (view, download PDF, pay, accept or decline)
• New: Stripe and PayPal payments with signed webhooks
• New: payment ledger, partial payments, Partially Paid status and balance due on pages, PDFs and the invoice list
• New: PDF receipts, emailed and downloadable
• New: Payments settings tab, email variables {view_link}, {pay_link}, {balance_due}, {amount_paid}, receipt email template
• New: "Preview" on every design card in Settings → General opens a sample PDF without creating a document
• Fixed: table headings such as "Unit price" no longer break onto two lines in any PDF design
• Fixed: the invoice / estimate details block in the Classic, Modern and Compact designs is compact instead of pushing labels and values to opposite edges
• Improved: Company logo field with preview, empty state and proper Choose / Change / Remove buttons; roomier settings forms; email variables grouped by email type; consistent list alignment and icon alignment in buttons
• Changed: editing the total of an invoice with payments keeps its status in line with the payments

1.0.0

• First release.

13. Support

Email support@wpexpertshub.com. To get a quick answer, include:

• Your order ID (or the email address used for the purchase).
• The plugin version (1.1.0 for this page), your WordPress version and your PHP version. For WooCommerce questions, the WooCommerce version too.
• What you did, what you expected and what happened, with the exact message you saw. For payment problems, the invoice's History lines and the gateway's webhook delivery result are the most useful; for email problems, the document's Email history; for order problems, the order notes and the wphub-advance-invoice entries in the WooCommerce logs.
• What you already tried. Never send your Stripe or PayPal secret keys or your licence key in an email.