PHPackages ejosterberg/opensalestax-whmcs - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. ejosterberg/opensalestax-whmcs ActiveLibrary[Payment Processing](/categories/payments) ejosterberg/opensalestax-whmcs ============================== WHMCS addon: replace WHMCS's built-in tax handling with the self-hosted OpenSalesTax engine for destination-based US sales tax on hosting / domain / SaaS invoices v0.1.0-alpha.3(3w ago)04Apache-2.0 OR GPL-2.0-or-laterPHPPHP >=8.2CI passing Since May 16Pushed 3w agoCompare [ Source](https://github.com/ejosterberg/opensalestax-whmcs)[ Packagist](https://packagist.org/packages/ejosterberg/opensalestax-whmcs)[ Docs](https://github.com/ejosterberg/opensalestax-whmcs)[ RSS](/packages/ejosterberg-opensalestax-whmcs/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (5)Versions (4)Used By (0) OpenSalesTax for WHMCS ====================== [](#opensalestax-for-whmcs) [![CI](https://github.com/ejosterberg/opensalestax-whmcs/actions/workflows/ci.yml/badge.svg)](https://github.com/ejosterberg/opensalestax-whmcs/actions/workflows/ci.yml)[![License](https://camo.githubusercontent.com/ed720b8af292f8fbd2691e43ae8fe3480ef13c19f1352c55557d0d7aaf490d1f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302532304f5225323047504c2d2d322e302d2d6f722d2d6c617465722d626c75652e737667)](#license) A WHMCS addon module that replaces WHMCS's built-in tax handling with the self-hosted [OpenSalesTax](https://github.com/ejosterberg/open-sales-tax-integrations) engine for **destination-based US sales tax** on hosting, domain, and SaaS invoices. > **Status:** v0.1.0-alpha — first installable release, hosting-provider integration testing pending. See [`specs/handoff.md`](specs/handoff.md) for the v0.2 roadmap. What it does ------------ [](#what-it-does) - Hooks into WHMCS's `InvoiceCreationPreEmail` event (the documented post-tax-calc, pre-email hook). - Reads the invoice + client billing details via WHMCS's Local API. - Recomputes the tax using your self-hosted OST engine, keyed on the client's billing ZIP-5. - Overwrites the invoice's `tax` and `taxrate` fields **before the customer email goes out**. - Logs everything to the WHMCS Activity Log under the `OpenSalesTax: ` prefix. What it does NOT do ------------------- [](#what-it-does-not-do) - Tax filing or remittance — the merchant remits. - Non-US destinations — anything outside `country = US` is left untouched (WHMCS default proceeds). - Non-USD invoices — same: untouched. - Per-product tax category mapping — every line is treated as `general` for v0.1 (per-category mapping is a v0.2 enhancement). - Address validation — we trust the WHMCS client's billing address. Install ------- [](#install) ### Via the merchant ZIP (recommended) [](#via-the-merchant-zip-recommended) 1. Download `opensalestax-whmcs-vX.Y.Z.zip` from the [Releases page](https://github.com/ejosterberg/opensalestax-whmcs/releases). 2. In WHMCS Admin: **System Settings -> Addon Modules -> Upload Module**, select the ZIP, click upload. 3. The addon now appears in the Addon Modules list. Click **Activate**. 4. Open **Addons -> OpenSalesTax** in the top nav. 5. Configure: - **Engine URL** — base URL of your self-hosted OST engine, e.g. `https://ostax.example.com`. - (optional) **API key** — bearer token if your engine is auth-gated. - **TLS verification** — leave `Yes` for production. - **Allow private-network engine URL** — `Yes` only for self-hosted-on-LAN. - **Fail hard on engine errors** — leave `No` (default) so engine outages don't block invoice creation. - **Per-state nexus filter** + **Nexus states** — leave the filter `No` to engage every US destination. - **Cache TTL (seconds)** — default `3600`. Lower for testing. 6. Save. 7. Create a test invoice for a US client — verify the tax line uses your destination-based engine output. ### Via composer (developer install) [](#via-composer-developer-install) ``` composer require ejosterberg/opensalestax-whmcs ``` This pulls the source, but you still need to copy `modules/addons/opensalestax/` into your WHMCS install. The ZIP build is the canonical merchant artifact. Compatibility ------------- [](#compatibility) **WHMCS**8.x (8.0+)**PHP**8.2 / 8.3 / 8.4**OpenSalesTax engine**v0.14+ (any release that ships the v1 calculate API)**OpenSalesTax PHP SDK**`ejosterberg/opensalestax ^0.1` (bundled in the ZIP)WHMCS 7.x is not officially supported; the addon-module API hooks have been stable since 7.0 but it's untested. Configuration reference ----------------------- [](#configuration-reference) Settings are stored in WHMCS's `tbladdonmodules` table under `module = 'opensalestax'`. KeyTypeDefaultNotes`engine_url`text(empty)Empty = addon is inert`api_key`password(empty)Optional bearer token`tls_verify`yes/noyesConstitution §6`allow_private_nets`yes/nonoConstitution §6`fail_hard`yes/nonoConstitution §5`nexus_enabled`yes/nonoConstitution §9`nexus_states`text(empty)Comma-separated 2-letter codes`cache_ttl_seconds`text3600Bounded 0-86400Architecture decisions ---------------------- [](#architecture-decisions) - **Hook choice:** `InvoiceCreationPreEmail` — see [`specs/decisions/001-hook-choice.md`](specs/decisions/001-hook-choice.md). - **Calculation only, never filing:** [`specs/constitution.md`](specs/constitution.md) §3. - **US + USD only:** [`specs/constitution.md`](specs/constitution.md) §4. - **Fail-soft default:** [`specs/constitution.md`](specs/constitution.md) §5. Development ----------- [](#development) ``` git clone https://github.com/ejosterberg/opensalestax-whmcs cd opensalestax-whmcs composer install composer check # PHPUnit + PHPStan max + composer audit ``` Built and tested with PHP 8.2 (XAMPP on Windows). See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the commit / DCO / dual-license rules. To produce the merchant ZIP locally: ``` PHP_BIN="/c/xampp/8.2.4/php/php.exe" \ COMPOSER_BIN="/c/xampp/8.2.4/php/php.exe /c/Users/ejosterberg/.local/bin/composer.phar" \ bash tools/build-zip.sh ``` (Linux / macOS users can drop the `PHP_BIN` / `COMPOSER_BIN` overrides if `php` and `composer` are on `$PATH`.) License ------- [](#license) Distributed under your choice of: - Apache License, Version 2.0 (`LICENSE-APACHE.txt`), OR - GNU GPL v2 or later (`LICENSE-GPL.txt`). SPDX expression: `Apache-2.0 OR GPL-2.0-or-later`. See [`LICENSE`](LICENSE) for details. Contributors agree their contributions are licensed under both options (see [`CONTRIBUTING.md`](CONTRIBUTING.md)). Disclaimer ---------- [](#disclaimer) > Tax calculations are provided as-is for convenience. The merchant is solely responsible for tax-collection accuracy and remittance to the appropriate jurisdictions. Verify against your state Department of Revenue before remitting. Sibling connectors ------------------ [](#sibling-connectors) - [`opensalestax-woocommerce`](https://github.com/ejosterberg/opensalestax-woocommerce) (WooCommerce) - [`opensalestax-opencart`](https://github.com/ejosterberg/opensalestax-opencart) (OpenCart 4.x) - [`opensalestax-magento`](https://github.com/ejosterberg/opensalestax-magento) (Magento 2) - [`opensalestax-bagisto`](https://github.com/ejosterberg/opensalestax-bagisto) (Bagisto) - [`opensalestax-invoice-ninja`](https://github.com/ejosterberg/opensalestax-invoice-ninja) (Invoice Ninja v5) - [`opensalestax-vendure`](https://github.com/ejosterberg/opensalestax-vendure) (Vendure) - [`opensalestax-saleor`](https://github.com/ejosterberg/opensalestax-saleor) (Saleor) - [`opensalestax-medusa`](https://github.com/ejosterberg/opensalestax-medusa) (Medusa) ### Health Score 36 — LowBetter than 79% of packages Maintenance95 Actively maintained with recent releases Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity34 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~2 days Total 3 Last Release 21d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b647ae9c341fdf92c36cb479ba7535c2eff9ac92f8614965a3b5953f7b543152?d=identicon)[ejosterberg](/maintainers/ejosterberg) --- Top Contributors [![ejosterberg](https://avatars.githubusercontent.com/u/6363457?v=4)](https://github.com/ejosterberg "ejosterberg (3 commits)") --- Tags billinghostingopensalestaxphpsales-taxtaxus-taxwhmcswhmcs-addonwhmcs-modulebillingWhmcstaxtax calculationsales taxhostingwhmcs-addonwhmcs moduleopensalestaxus-tax ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/ejosterberg-opensalestax-whmcs/health.svg) ``` [![Health](https://phpackages.com/badges/ejosterberg-opensalestax-whmcs/health.svg)](https://phpackages.com/packages/ejosterberg-opensalestax-whmcs) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k31.1k11](/packages/tempest-framework)[avalara/avataxclient Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API. 528.3M7](/packages/avalara-avataxclient) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)