WooNooW/TAX_SETTINGS_DESIGN.md

Tax Settings Design - WooNooW

Philosophy: Zero Learning Curve

User should understand tax setup in 30 seconds, not 30 minutes.

---

UI Structure

Tax Settings Page
├── [Toggle] Enable tax calculations
│   └── Description: "Calculate and display taxes at checkout"
│
├── When ENABLED, show:
│
├── Predefined Tax Rates [SettingsCard]
│   └── Based on store country from Store Details
│   
│   Example for Indonesia:
│   ┌─────────────────────────────────────┐
│   │ 🇮🇩 Indonesia Tax Rates             │
│   ├─────────────────────────────────────┤
│   │ Standard Rate: 11%                  │
│   │ Applied to: All products            │
│   │ [Edit Rate]                         │
│   └─────────────────────────────────────┘
│
├── Additional Tax Rates [SettingsCard]
│   ├── [+ Add Tax Rate] button
│   └── List of custom rates:
│       ┌─────────────────────────────────┐
│       │ Malaysia: 6%                    │
│       │ Applied to: All products        │
│       │ [Edit] [Delete]                 │
│       └─────────────────────────────────┘
│
├── Display Settings [SettingsCard]
│   ├── Prices are entered: [Including tax / Excluding tax]
│   ├── Display prices in shop: [Including tax / Excluding tax]
│   └── Display prices in cart: [Including tax / Excluding tax]
│
└── Advanced Settings
    └── Link to WooCommerce tax settings

---

Predefined Tax Rates - Smart Detection

Source: WooCommerce General Settings → "Selling location(s)"

Scenario 1: Sell to Specific Countries

If user selected specific countries (e.g., Indonesia, Malaysia):

Predefined Tax Rates
├── 🇮🇩 Indonesia: 11% (PPN)
└── 🇲🇾 Malaysia: 6% (SST)

Scenario 2: Sell to All Countries

If user selected "Sell to all countries":

Predefined Tax Rates
└── Based on store country:
    🇮🇩 Indonesia: 11% (PPN)

Additional Tax Rates
└── [+ Add Tax Rate] → Shows all countries

Scenario 3: Sell to Specific Continents

If user selected "Asia":

Suggested Tax Rates (Asia)
├── 🇮🇩 Indonesia: 11%
├── 🇲🇾 Malaysia: 6%
├── 🇸🇬 Singapore: 9%
├── 🇹🇭 Thailand: 7%
├── 🇵🇭 Philippines: 12%
└── 🇻🇳 Vietnam: 10%

Standard Tax Rates by Country

Country	Standard Rate	Note
Indonesia	11%	PPN (VAT)
Malaysia	6%	SST
Singapore	9%	GST
Thailand	7%	VAT
Philippines	12%	VAT
Vietnam	10%	VAT
United States	0%	Varies by state - user adds manually
European Union	20%	Average - varies by country

---

User Flow

Scenario 1: Indonesian Store (Simple)

1. User enables tax toggle
2. Sees: "🇮🇩 Indonesia: 11% (Standard)"
3. Done! Tax is working.

Scenario 2: Multi-Country Store

1. User enables tax toggle
2. Sees predefined rate for their country
3. Clicks "+ Add Tax Rate"
4. Selects country: Malaysia
5. Rate auto-fills: 6%
6. Clicks Save
7. Done!

Scenario 3: US Store (Complex)

1. User enables tax toggle
2. Sees: "🇺🇸 United States: 0% (Add rates by state)"
3. Clicks "+ Add Tax Rate"
4. Selects: United States - California
5. Enters: 7.25%
6. Clicks Save
7. Repeats for other states

---

Add Tax Rate Dialog

Add Tax Rate
├── Country/Region [Searchable Select]
│   └── 🇮🇩 Indonesia
│       🇲🇾 Malaysia
│       🇺🇸 United States
│       └── California
│           Texas
│           New York
│
├── Tax Rate (%)
│   └── [Input: 11]
│
├── Tax Class
│   └── [Select: Standard / Reduced / Zero]
│
└── [Cancel] [Save Rate]

---

Backend Requirements

API Endpoints:

• GET /settings/tax/config - Get tax enabled status + rates
• POST /settings/tax/toggle - Enable/disable tax
• GET /settings/tax/rates - List all tax rates
• POST /settings/tax/rates - Create tax rate
• PUT /settings/tax/rates/{id} - Update tax rate
• DELETE /settings/tax/rates/{id} - Delete tax rate
• GET /settings/tax/suggested - Get suggested rates based on selling locations

Get Selling Locations:

// Get WooCommerce selling locations setting
$selling_locations = get_option('woocommerce_allowed_countries');
// Options: 'all', 'all_except', 'specific'

if ($selling_locations === 'specific') {
    $countries = get_option('woocommerce_specific_allowed_countries');
    // Returns array: ['ID', 'MY', 'SG']
}

// Get store base country
$store_country = get_option('woocommerce_default_country');
// Returns: 'ID:JB' (country:state) or 'ID'

Predefined Rates Data:

{
  "ID": {
    "country": "Indonesia",
    "rate": 11,
    "name": "PPN (VAT)",
    "class": "standard"
  },
  "MY": {
    "country": "Malaysia",
    "rate": 6,
    "name": "SST",
    "class": "standard"
  }
}

---

Benefits

✅ Zero learning curve - User sees their country's rate immediately ✅ No re-selection - Store country from Store Details is used ✅ Smart defaults - Predefined rates are accurate ✅ Flexible - Can add more countries/rates as needed ✅ Accessible - Clear labels, simple toggle ✅ Scalable - Works for single-country and multi-country stores

---

Comparison to WooCommerce

Feature	WooCommerce	WooNooW
Enable tax	Checkbox buried in settings	Toggle at top
Add rate	Navigate to Tax tab → Add rate → Fill form	Predefined + one-click add
Multi-country	Manual for each	Smart suggestions
Learning curve	30 minutes	30 seconds

---

Next Steps

1. Create Tax settings page component
2. Build backend API endpoints
3. Add predefined rates data
4. Test with Indonesian store
5. Test with multi-country store