Skip to content

City Tax Configuration Documentation

Menu Location: Payments > Taxes > City Tax

Access Level: Administrator and above

Last Updated: 2026-03-01

Overview

The City Tax page manages sales tax rates at the city level. Configure which cities charge sales tax and set their specific tax rates for automatic calculation on orders.

Primary Functions:

  • Add new cities with tax rates
  • Edit existing city tax rates
  • Assign cities to counties
  • View all configured city taxes
  • Delete city tax configurations
  • Automatically apply tax to orders based on customer city

Page Layout

Header Section

  • Page Title: City Tax configuration
  • Add New Button: Create new city tax entry

Main Content Table

Searchable, sortable table showing all configured city tax rates

Table Columns:

  • City Name
  • Tax Rate (percentage)
  • County Assignment
  • State
  • Actions (Edit/Delete)

City Tax Fields

Required Fields

City Name:

  • Full city name as it appears in customer addresses
  • Must match exactly (case-insensitive)
  • Example: "Grand Rapids" not "GR" or "Grand Rpds"

Tax Rate:

  • Percentage as decimal number
  • Example: 6.5 for 6.5% tax
  • Do not include % symbol
  • Can include decimals (6.75, 7.125, etc.)

Optional Fields

County:

  • Select from existing counties
  • Links city to county for combined tax calculation
  • Leave blank if city has no county tax

State:

  • Two-letter state abbreviation
  • Helps prevent duplicate city names across states
  • Example: MI, CA, TX

Managing City Taxes

Adding a New City Tax

Steps:

  1. Click "Add New" button
  2. Enter city name exactly as it appears in addresses
  3. Enter tax rate as decimal (e.g., 6.5 for 6.5%)
  4. (Optional) Select county from dropdown
  5. (Optional) Enter state abbreviation
  6. Click "Save"
  7. New city tax appears in table

Example:

  • City Name: Grand Rapids
  • Rate: 1.5
  • County: Kent County
  • State: MI
  • Result: 1.5% city tax + county tax for Grand Rapids, MI orders

Editing a City Tax

Steps:

  1. Find city in table (use search if needed)
  2. Click "Edit" icon
  3. Modify name, rate, or county
  4. Click "Save"
  5. Changes apply immediately to new orders

When to Edit:

  • Tax rate changes enacted by city
  • Correcting entry errors
  • Reassigning county
  • Updating city name spelling

Deleting a City Tax

Steps:

  1. Find city in table
  2. Click "Delete" icon
  3. Confirm deletion
  4. City tax removed from system

Warning: Deleting does not affect historical orders, only future orders.

When to Delete:

  • City eliminated sales tax
  • City was entered in error
  • Consolidating duplicate entries

How City Taxes Work

Automatic Tax Calculation

Process:

  1. Customer enters shipping address at checkout
  2. System reads city name from address
  3. System looks up city in tax table
  4. If match found, city tax rate applied to order
  5. City tax added to order total
  6. City tax tracked separately for reporting

Matching Logic:

  • Case-insensitive comparison
  • Exact match required
  • Spaces and punctuation must match

Example Order:

  • Customer City: Grand Rapids
  • City Tax Rate: 1.5%
  • Order Subtotal: $100
  • City Tax Applied: $1.50
  • Plus county tax, state tax, etc.

Combined with Other Taxes

City taxes combine with other tax levels:

  • State Tax: Applied to all orders in state
  • County Tax: Applied if county configured
  • Zip Tax: Applied if zip configured
  • Product Tax: Item-specific taxes

Total Tax = State + County + City + Zip + Product Taxes

Common Use Cases

Use Case 1: Add Tax for New City

Goal: Configure city tax when city enacts sales tax

Steps:

  1. Research exact tax rate from city ordinance
  2. Verify county assignment
  3. Click "Add New" in City Tax page
  4. Enter city name: "Springfield"
  5. Enter rate: 1.0 (for 1%)
  6. Select county if applicable
  7. Enter state: IL
  8. Click "Save"
  9. Test with sample order to Springfield

Verification:

  • Create test order with Springfield address
  • Verify 1% city tax appears on order
  • Check tax reporting shows city tax separately

Use Case 2: Update Tax Rate

Goal: Change city tax rate after rate change

Steps:

  1. Obtain official notice of new rate
  2. Note effective date
  3. On effective date, go to City Tax page
  4. Search for city name
  5. Click "Edit"
  6. Update rate to new percentage
  7. Click "Save"
  8. Notify accounting of change

Tips:

  • Schedule rate change for midnight or early morning
  • Update on exact effective date per ordinance
  • Keep documentation of rate change notice
  • Review first few orders to confirm correct tax

Use Case 3: Cleanup Duplicate Cities

Goal: Remove duplicate entries causing incorrect tax

Steps:

  1. Search table for city name
  2. Identify duplicate entries
  3. Determine which entry is correct
  4. Note order history with each entry
  5. Delete incorrect duplicate
  6. Edit remaining entry if needed
  7. Test address matching

Common Duplicates:

  • "Saint Paul" vs. "St. Paul"
  • "Fort Worth" vs. "Ft. Worth"
  • Different spellings or abbreviations

Use Case 4: Configure New Service Area

Goal: Set up taxes for expanding to new city

Steps:

  1. Research city tax requirements
  2. Verify if city has local sales tax
  3. If yes, obtain exact rate
  4. Determine if city is in county (for county tax)
  5. Add city to City Tax table
  6. Add county if not already configured
  7. Test with sample address
  8. Update zip code taxes if needed
  9. Begin serving customers in new city

Use Case 5: Audit Tax Configuration

Goal: Verify all cities have correct rates

Steps:

  1. Export city tax table to CSV
  2. Compare against authoritative source
  3. Note any discrepancies
  4. Research correct rates for mismatches
  5. Update incorrect entries
  6. Document audit date and findings
  7. Schedule next audit (annually or semi-annually)

Troubleshooting

City Tax Not Applying to Orders

Symptoms:

  • Customer in configured city
  • No city tax on order
  • State/county tax working fine

Check:

  1. Verify city name spelling in tax table
  2. Compare to exactly how customer entered it
  3. Check for extra spaces or punctuation
  4. Verify customer address has city filled in
  5. Confirm city entry is not deleted
  6. Test with different address formats

Common Causes:

  • City name mismatch ("St Paul" vs. "Saint Paul")
  • Extra spaces in city name entry
  • Customer abbreviated city name
  • City field empty in customer address

Solutions:

  • Add common spelling variations as separate entries
  • Standardize city names in customer addresses
  • Document accepted city name format

Wrong Tax Rate Applied

Symptoms:

  • City tax appears on order
  • Amount is incorrect
  • Rate doesn't match tax table

Investigation:

  1. View city entry in tax table
  2. Note configured rate
  3. Check order details for applied rate
  4. Verify rate decimal format (6.5 not 0.065)
  5. Check if multiple cities match

Common Causes:

  • Rate entered wrong (6.5% as 0.065 instead of 6.5)
  • Duplicate city entries with different rates
  • Rate updated but order uses old cached rate

Solutions:

  • Correct rate in tax table
  • Delete duplicate entries
  • Verify rate format (percentage as decimal)

Tax Shows on Report but Not in Table

Symptoms:

  • Tax report shows city tax collected
  • City not in configuration table
  • Historical city tax entries

Explanation: This is normal. Historical orders retain their original tax calculations even if city is later removed from configuration. Tax reports show ALL taxes ever collected, not just currently configured cities.

This is expected behavior - ensures accurate historical reporting

  • County Tax - Configure county-level taxes
  • State Tax - Configure state-level taxes
  • Zip Code Tax - Configure zip-level taxes
  • Tax Reports - View tax collection reports
  • Orders - See applied taxes on individual orders

Workflow:

  1. Configure state, county, city, zip taxes
  2. Taxes auto-apply to orders based on address
  3. Review Tax Reports for collection summary

Permissions & Access

Required Access Level: Administrator or higher

Access Level Capabilities:

  • Administrator: Add, edit, delete city taxes
  • Kiva Admin: All features + bulk import tools

Restricted Features:

  • Only Administrators can modify tax rates
  • Tax changes affect future orders immediately

Best Practices

Configuration Management

  1. Keep city names consistent with USPS standards
  2. Document tax rate sources (city ordinances)
  3. Add effective date notes when rates change
  4. Test after any configuration change
  5. Maintain audit trail of rate changes

Rate Updates

  1. Subscribe to city tax rate change notifications
  2. Update rates on exact effective date
  3. Coordinate with accounting team
  4. Update multiple systems simultaneously
  5. Verify first orders after rate change

Data Quality

  • Use official city names, not nicknames
  • Standardize format (St. vs. Saint)
  • Add common variations as needed
  • Remove obsolete entries annually
  • Cross-reference with authoritative sources

Compliance

  • Document source of each tax rate
  • Keep records of rate change notices
  • Audit configuration annually
  • Maintain historical rate information
  • Coordinate with tax accountant

Quick Reference Card

Task Action/Location
Add new city tax Click "Add New", enter details, save
Edit city rate Find city, click "Edit", update rate
Delete city Find city, click "Delete", confirm
Search for city Use table search box
Sort by rate Click "Rate" column header
Verify city tax Check Tax Reports for city breakdown
Test city tax Create test order with city address
Export city list Use table export (if available)

FAQs

Do I need to add every city we serve?

No, only add cities that have their own local sales tax. Many cities don't have city-specific taxes. Research each city's tax requirements before adding.

How do I know if a city has local sales tax?

Check with your state's department of revenue, the city's finance department, or use tax rate lookup tools like Avalara or TaxJar. Many states publish local tax rate tables.

What if a city name appears in multiple states?

Add the state abbreviation to differentiate. The system can handle "Springfield, IL" and "Springfield, MO" as separate entries with different rates.

Can I set different rates for different zip codes in the same city?

Use the Zip Code Tax configuration for zip-specific rates. City tax applies uniformly across the entire city; zip tax allows more granular control.

What happens if I enter the rate wrong (0.065 instead of 6.5)?

Orders will calculate with incorrect tax (0.065% instead of 6.5%). Correct the rate immediately, then manually adjust any affected orders. Test after correcting.

Do city taxes apply to shipping/delivery fees?

This depends on your tax configuration settings and local tax laws. Consult with your tax accountant about whether city tax should apply to delivery fees in your jurisdiction.

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.