Nextcloud Invoice Feeder uploads WHMCS invoice PDFs to Nextcloud over WebDAV. It supports automatic uploads after payment, manual upload by invoice ID, retries for failed uploads and CSV export of upload history.
The module copies PDFs. It is not an accounting ledger, a credit-note generator or a complete backup of WHMCS. Verify that important documents exist in Nextcloud and keep your normal accounting and backup procedures.
Requirements
- A supported WHMCS installation and a module package compatible with its PHP environment.
- A Nextcloud account with WebDAV access, available storage and permission to create files and folders in the destination.
- A Nextcloud app password and a valid module license.
- HTTPS connectivity from the WHMCS server to Nextcloud.
Installation and connection
- Back up your WHMCS files and database.
- Upload the module to
/modules/addons/nextcloud_invoice_feeder/. - Activate it in System Settings > Addon Modules, or Setup > Addon Modules in older layouts. Enter the license key and set administrator access.
- In Nextcloud, open Settings > Security and create an app password for this integration.
- Configure the WebDAV URL, Nextcloud username and app password in the addon settings.
- Choose the base path and folder structure. Save the configuration, then open Addons > Nextcloud Invoice Feeder and use Test Connection.
- Upload one suitable paid test invoice and confirm that its PDF can be opened in the expected Nextcloud folder.
The WebDAV URL includes the user's file area, for example https://cloud.example.com/remote.php/dav/files/username/. Use the actual WebDAV address supplied by your Nextcloud installation. An app password can be revoked independently of the main account password.
A successful connection test checks access to the WebDAV endpoint. It does not prove that PDF generation, destination-folder creation and file upload all work; the test invoice checks those steps.
Folder and filename settings
Base Path is the destination folder, such as Company/Finance/. The module supports these structures beneath it:
- Year/Quarter/Invoices
- Year/Quarter
- Year/Month
- Year only
- Flat, with no date subfolders
Folder dates and the date in the filename come from the invoice date, not the payment or upload date. The normal filename is YYYYMMDD_InvoiceNum_ClientName.pdf. Cancellation/refund uploads use YYYYMMDD_CANCELLED_InvoiceNum_ClientName.pdf.
The module prefers the company name when available and otherwise uses the client's name. It removes unsupported characters and shortens the name for the filename. Check the stored path in the upload history instead of guessing the exact result.
Automatic uploads
Enable automatic uploading in the addon configuration. The InvoicePaid hook calls the upload function, which generates a WHMCS PDF and uploads it during that request. This is not a background queue, so slow PDF generation or WebDAV responses can delay the triggering request.
The cancellation/refund setting controls the additional hooks:
- On cancellation, the module checks for the original PDF at its expected Nextcloud path before attempting the CANCELLED copy. A previously paid invoice alone does not establish that this check will pass.
- On refund, the module attempts a CANCELLED copy through the refund hook.
The CANCELLED filename is an archive convention. It does not create a legally valid credit note or replace your refund/accounting process.
Manual upload and retries
For a manual upload, enter the internal WHMCS invoice ID on the addon page and click Upload Invoice. The normal manual-upload path requires a paid invoice.
Successful uploads are tracked by invoice and document state. If a matching success already exists in the module history, the function returns an already-uploaded result rather than forcing another upload. Do not use the manual button as a guaranteed way to replace or recover a file deleted from Nextcloud.
After fixing a connection, permission or storage problem, use Retry Failed Uploads. Each run processes up to 50 failed entries. Review individual results before repeating the operation. If a cancellation or refund remains unresolved, ask support to check its state rather than assuming the paid-invoice manual path will recreate it.
History and failed uploads
The addon records invoice details, file paths, status and errors in mod_nextcloud_feeder_log. Deactivation preserves this history. Use the module's history view and Export Logs to CSV for reconciliation.
Upload exceptions are logged and the module attempts to create a WHMCS To-Do item for an enabled administrator. A missing To-Do does not prove that every upload succeeded. Review the module history and WHMCS Activity Log, then verify the actual file in Nextcloud.
Troubleshooting
- Connection failure: Check the full WebDAV URL, username, app password, certificate and network access from WHMCS. Do not work around certificate problems by exposing credentials over public HTTP.
- Connection succeeds but upload fails: Check destination write permission, folder creation, storage quota and WHMCS PDF generation.
- File appears in the wrong period: Compare its path with the invoice date and configured structure.
- Already uploaded but file missing: Check whether it was moved or deleted in Nextcloud. Preserve the history and contact support before changing records.
- WHMCS upgrade affects authentication: Use the current package; version 1.1 includes handling for encrypted addon password settings in WHMCS 9.
For support, include module, WHMCS, PHP and Nextcloud versions, the invoice ID, connection-test result and redacted error text. Never include the app password.
