Skip to content

Commit b044262

Browse files
newlinewebdesignnewlinewebdesign
authored
docs: add Advanced Tax Rates app user guide (#64)
* docs(payment-methods): add Stripe, Kustom guides and move PayPal to payment-methods/ New pages: - Stripe Payment user guide (embedded/hosted modes, webhooks, saved cards, refunds) - Kustom Payment user guide (KCO/HPP modes, refunds, capture) Moved: - PayPal Payment from payment/ to payment-methods/ (consolidate all payment gateway docs) * docs(developer): add saved payment methods event and update payment profiles New pages: - Saved Payment Methods Event (onJ2CommerceGetSavedPaymentMethods) developer guide Updated pages: - Payment Profiles Table (added unified tab integration section) * docs: remove PayPal from payment/ (moved to payment-methods/) * docs: add Advanced Tax Rates app user guide
1 parent 4c4ca0d commit b044262

File tree

1 file changed

+227
-0
lines changed

1 file changed

+227
-0
lines changed

‎website/docs-v6/apps-and-extensions/apps/app-taxrate.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: "Advanced Tax Rates"
3+
sidebar_label: "Advanced Tax Rates"
4+
sidebar_position: 22
5+
description: "Configure custom tax classes with granular tax rates matched by country, zone, postcode, and address type in J2Commerce."
6+
---
7+
8+
# Advanced Tax Rates
9+
10+
The Advanced Tax Rates app lets you create custom tax classes with precise rules for how tax is calculated at checkout. Each rule can match by country, state or zone, postcode (including wildcards), and whether the rate applies to the billing or shipping address.
11+
12+
This is useful when your tax obligations vary by location — for example, applying a different rate for customers in a specific state or postal code range — and when the built-in tax profile system alone is not detailed enough to cover your requirements.
13+
14+
## Requirements
15+
16+
- PHP 8.3.0 or higher
17+
- Joomla! 6.x
18+
- J2Commerce 6.x
19+
20+
## Installation
21+
22+
This plugin is a separate add-on available from the [J2Commerce Extensions Store](https://www.j2commerce.com). It is not included with the core J2Commerce 6 component.
23+
24+
1. Purchase and download the `plg_j2commerce_app_taxrate.zip` package from the J2Commerce website.
25+
2. Go to **System** -> **Install** -> **Extensions**.
26+
3. Upload the ZIP file. The plugin installs and enables automatically.
27+
28+
<!-- SCREENSHOT: System > Install > Extensions upload screen -->
29+
30+
## Enable the Plugin
31+
32+
If the plugin did not enable automatically after installation:
33+
34+
1. Go to **System** -> **Manage** -> **Extensions**.
35+
2. Search for **Advanced Tax Rates**.
36+
3. Click the status toggle to enable it (it turns green).
37+
38+
You can also reach the plugin from **J2Commerce** -> **Apps**. Search for **Advanced Tax Rates** and enable it there.
39+
40+
<!-- SCREENSHOT: J2Commerce > Apps list showing Advanced Tax Rates plugin with enable toggle -->
41+
42+
## Open the Plugin Settings
43+
44+
1. Go to **J2Commerce** -> **Apps**.
45+
2. Find **Advanced Tax Rates** in the list and click its title to open the settings.
46+
47+
The plugin configuration page contains two sections:
48+
49+
- **Tax Classes** — where you manage your tax classes and their rates
50+
- **Advanced** — a postcode suffix option and debug mode toggle
51+
52+
<!-- SCREENSHOT: Advanced Tax Rates plugin configuration page showing Tax Classes section -->
53+
54+
## How It Works
55+
56+
The Advanced Tax Rates plugin extends J2Commerce's tax system with a two-level structure:
57+
58+
1. **Tax Class** — a named group (for example, "Standard VAT" or "Reduced Rate"). You assign a tax class to a product the same way you assign a built-in tax profile.
59+
2. **Tax Rates** — one or more rules inside a tax class. Each rule specifies which country, zone, postcode, and address type it applies to, along with the percentage rate.
60+
61+
When J2Commerce calculates tax at checkout, it finds the tax class assigned to the product, then evaluates all the rules inside that class against the customer's address to determine which rates apply.
62+
63+
## Managing Tax Classes
64+
65+
### Create a Tax Class
66+
67+
1. On the plugin configuration page, click the **New Tax Class** button.
68+
2. Enter a **Tax Class Name** (required).
69+
3. Set the **Enabled** field to *Enabled*.
70+
4. Click **Save**.
71+
72+
The new class appears in the tax classes table.
73+
74+
<!-- SCREENSHOT: New Tax Class modal showing class name and enabled fields -->
75+
76+
### Edit a Tax Class
77+
78+
Click the class name in the table to open the edit form. Change the name or enabled state and click **Save**.
79+
80+
### Enable or Disable a Tax Class
81+
82+
Click the toggle icon in the **Enabled** column of the tax classes table. The icon updates immediately — no page reload required.
83+
84+
### Delete a Tax Class
85+
86+
Click the trash icon next to the class. You will be asked to confirm. Deleting a tax class also deletes all its associated tax rates — this cannot be undone.
87+
88+
## Assigning a Tax Class to a Product
89+
90+
Tax classes created by this plugin appear in the **Tax Profile** dropdown when editing a product, alongside any built-in tax profiles.
91+
92+
1. Go to **J2Commerce** -> **Catalog** -> **Products**.
93+
2. Open the product you want to configure.
94+
3. Find the **Tax Profile** field and select your tax class from the dropdown.
95+
4. Save the product.
96+
97+
<!-- SCREENSHOT: Product edit form showing Tax Profile dropdown with custom tax class selected -->
98+
99+
## Managing Tax Rates
100+
101+
Click the **View / Edit Rates** button next to a tax class to open the tax rates panel.
102+
103+
### Add a New Rate
104+
105+
The top section of the rates panel contains the "Add New Tax Rate" form. Fill in the fields and click **New**:
106+
107+
| Field | Description | Example |
108+
|-------|-------------|---------|
109+
| **Country** | The country this rate applies to. Select `*` for all countries. | `USA` |
110+
| **Zone** | The state or zone within the country. Select `*` for all zones. | `CA` |
111+
| **Postcode** | The postal code. Supports wildcards (see below). | `90*` |
112+
| **Address Type** | Whether this rate matches the **Billing** or **Shipping** address. | `Billing` |
113+
| **Rate (%)** | The tax percentage to apply. | `8.5` |
114+
| **Rate Name** | A label shown on invoices and order summaries. | `CA Sales Tax` |
115+
| **Priority** | Determines the order rates are applied when multiple rates match. Lower numbers run first. | `0` |
116+
117+
<!-- SCREENSHOT: Add New Tax Rate form inside the tax rates modal -->
118+
119+
### Postcode Wildcards
120+
121+
Postcode matching supports partial wildcards. Use an asterisk (`*`) at the end of a partial postcode to match all postcodes that begin with those characters.
122+
123+
| Postcode value | What it matches |
124+
|---------------|----------------|
125+
| `*` | Any postcode |
126+
| `90210` | Only postcode 90210 exactly |
127+
| `90*` | All postcodes starting with 90 |
128+
| `SW1A*` | All postcodes starting with SW1A |
129+
130+
This lets you define rates for broad regions without listing every individual postcode.
131+
132+
### Edit Existing Rates
133+
134+
All existing rates appear in the table below the "Add" form. Edit the fields directly in the table rows. When you are done making changes, click **Save All** to save every row at once.
135+
136+
### Delete a Rate
137+
138+
Click the trash icon at the end of a rate row. Confirm the prompt. The row is removed immediately without needing to save.
139+
140+
## Importing Tax Rates from CSV
141+
142+
For large rate tables, you can import rates from a CSV file instead of entering them one by one.
143+
144+
### Prepare Your CSV File
145+
146+
The CSV file must have these column headers in the first row:
147+
148+
```
149+
taxrate_country,taxrate_zone,taxrate_zip,address_type,taxrate_rate,taxrate_name,taxrate_priority
150+
```
151+
152+
Each subsequent row is one tax rate. Values follow the same rules as the manual entry form — use `*` for wildcards.
153+
154+
**Example CSV content:**
155+
156+
```
157+
taxrate_country,taxrate_zone,taxrate_zip,address_type,taxrate_rate,taxrate_name,taxrate_priority
158+
USA,CA,*,billing,8.25,California Sales Tax,0
159+
USA,NY,*,billing,8.875,New York Sales Tax,0
160+
GBR,*,*,billing,20,UK VAT Standard,0
161+
GBR,*,*,billing,5,UK VAT Reduced,1
162+
```
163+
164+
### Run the Import
165+
166+
1. In the tax classes table, click the **Import** button next to the class you want to populate.
167+
2. Either upload a CSV file using the file picker, or enter the file path on the server.
168+
3. If your file uses a delimiter other than a comma (for example, a semicolon), enter it in the **Delimiter** field.
169+
4. Click **Import**.
170+
171+
A confirmation message tells you how many rows were imported successfully. If any rows had formatting errors they are skipped and counted separately.
172+
173+
<!-- SCREENSHOT: CSV Import modal showing file upload, path, and delimiter fields -->
174+
175+
:::info
176+
Importing does not replace existing rates — it adds to them. To reset a class's rates before importing, delete the existing rates manually first.
177+
:::
178+
179+
## Exporting Tax Rates to CSV
180+
181+
Click the **Export CSV** button next to a tax class to download all of its rates as a CSV file. This is useful for:
182+
183+
- Backing up rates before making bulk changes
184+
- Sharing rate tables between stores
185+
- Editing a large rate set offline and re-importing
186+
187+
## Advanced Settings
188+
189+
### Ignore Postcode Suffix
190+
191+
Some customers enter postcodes with a hyphen suffix, such as `94403-1234`. The suffix is the part after the hyphen. When this option is enabled (the default), the suffix is stripped before matching — so `94403-1234` is treated as `94403`.
192+
193+
Enable this setting if customers may enter extended postcodes and your rate rules only specify the base postcode.
194+
195+
### Debug Mode
196+
197+
Enables detailed logging to `administrator/logs/app_taxrate.php`. Use this setting when investigating why a particular tax rate is (or is not) being applied to an order. Turn it off when you are done troubleshooting — debug logging adds overhead to every tax calculation.
198+
199+
## Troubleshooting
200+
201+
### A rate is not being applied at checkout
202+
203+
**Cause:** The matching rules may not align with the customer's address.
204+
205+
**Checklist:**
206+
207+
1. Confirm the product has the correct tax class assigned in its **Tax Profile** field.
208+
2. Open the tax class and check each rate's **Country**, **Zone**, and **Postcode** values.
209+
3. Verify **Address Type** matches how your store is configured — billing or shipping.
210+
4. Enable **Debug Mode** in the Advanced settings and place a test order. Review the log at `administrator/logs/app_taxrate.php` to see which rates were evaluated.
211+
212+
### The tax class does not appear in the product Tax Profile dropdown
213+
214+
**Cause:** The tax class is disabled.
215+
216+
**Solution:** Go to the plugin configuration page and enable the tax class using the toggle in the Enabled column.
217+
218+
### Import shows 0 rows imported
219+
220+
**Cause:** The CSV header row does not match the expected column names.
221+
222+
**Solution:** Ensure the first row of your CSV contains exactly: `taxrate_country,taxrate_zone,taxrate_zip,address_type,taxrate_rate,taxrate_name,taxrate_priority` — spelling and case must match.
223+
224+
## Related Topics
225+
226+
- [Tax Profiles](../../configuration/tax-profiles.md)
227+
- [Data Validation](./app-validationrules.md)

0 commit comments

Comments
 (0)