User Guide

1. Managing Tax Rules

The Tax Rules tab is the core of VapeTax. It displays all 63 state excise tax rules in a searchable, filterable table. On install, every rule is pre-loaded with Tax Foundation 2026 data.

Filtering and Searching

Use the filter buttons at the top to narrow the view:

• All — Shows every state rule
• Taxed — States with an active excise tax method (not "none")
• No Tax — States where the method is "none" (16 states)
• Disabled — States you've toggled off

The search bar filters by state name or state code.

Enabling and Disabling States

Use the toggle switch on each row to enable or disable a state. Disabled states return $0 tax at checkout regardless of their configured rate. This is useful for states where you don't have nexus.

Editing a Rule

Click Edit on any state to open the rule editor. Fields you can change:

• Tax Method — pct_wholesale, pct_retail, pct_mfg, per_ml, per_cartridge, or none
• Rate — The tax rate (0.95 = 95%, or $0.05 for per_ml, or $1.50 for per_cartridge)
• System Type — All, Open, or Closed (for bifurcated states)
• Volume Threshold — mL threshold for states like Maryland and Nebraska
• Threshold Direction — "above" or "at or below" the threshold
• Nicotine Required — For Washington's nicotine split rules
• Notes — Your own notes about the rule

Click Save to apply. Changes take effect on the next checkout.

2. Products & Classification

The Products tab displays your synced BigCommerce catalog. Products are grouped by parent with expandable variant rows.

Syncing Your Catalog

Click Sync Catalog to pull the latest products and variants from your BigCommerce store. This overwrites product names, SKUs, and prices, but does not overwrite your classifications. Run a sync whenever you add new products to your store.

Classifying Products

Each vape product needs a product type so VapeTax knows how to calculate tax. Click Classify on a product to set:

• Product Type — Open Liquid, Closed Pod, Closed Disposable, Device, or Accessory
• Volume (mL) — The liquid volume, required for per_ml states and volume threshold states
• Cartridge Count — Number of pods/cartridges in the pack, required for per_cartridge states
• Contains Nicotine — Toggle for Washington state's nicotine split
• Wholesale Cost — Your cost, used by pct_wholesale and pct_mfg states

Classify All (Parent Products)

For parent products with variants, click Classify All to cascade the product type and nicotine flag to every variant at once. Individual variants can still be edited separately afterward — useful when variants have different volumes.

Ignoring Non-Vape Products

If your catalog includes merchandise, accessories, or other non-vape items, click Ignore to exclude them from tax calculation. Ignored products appear greyed out with an "IGNORED" badge. Use Ignore All on a parent to cascade. Click Unignore to reset.

Pagination and Search

Products are paginated at 25 per page. Use the search bar to find products by name or SKU. Filter buttons let you view: All, Taxable, Needs Classification, Ignored, or Devices/Accessories.

3. Markup Configuration

The Markup tab controls your default wholesale and retail markup percentages. These are fallback values used when VapeTax needs to estimate a price that isn't available from your BigCommerce catalog.

When Markups Are Used

• Wholesale markup — Applied when a state uses pct_wholesale and no wholesale cost is set on the product
• Retail markup — Applied when a state uses pct_retail and no retail price is available from BigCommerce

If your BigCommerce products have accurate retail prices set, VapeTax uses those directly at checkout. The markup percentages are only a safety net.

Default Values

Defaults are 5% wholesale and 30% retail, based on Tax Foundation industry assumptions. Adjust these to match your actual margins for more accurate tax calculation.

4. Compliance Reports (Pro Plan)

The Reports tab provides tax calculation history for compliance filing. This tab is available on the Pro plan ($99.99/mo).

Date Range Selection

Use the date pickers or quick-select buttons: This Month, Last Month, This Quarter, Last Quarter, This Year, Last Year. The report updates automatically when you change the range.

Summary Cards

At the top, four cards show the totals for the selected period: total excise tax collected, total orders with tax, total taxable amount, and number of states with activity.

State Breakdown

The table below shows excise tax, sales tax, order count, and total tax for each state that had activity in the selected period.

CSV Export

Click Export CSV to download the report as a spreadsheet. The CSV includes a totals row at the bottom. Use this for quarterly or annual filing with your accountant or state revenue department.

5. Settings & Connection

The Settings tab shows your store information, tax provider connection status, and subscription management.

Store Information

Displays your store name, store hash, current plan, subscription status, trial end date (if applicable), and install date.

Tax Provider Connection

Click Register Connection to generate credentials and register VapeTax with BigCommerce's Tax Provider API. After registering, go to Settings → Tax in your BigCommerce control panel and select VapeTax as your tax provider.

6. Billing & Subscription

Feature	Base ($49.99/mo)	Pro ($99.99/mo)
Excise tax at checkout	Yes	Yes
Sales tax at checkout	Yes	Yes
Product classification	Yes	Yes
50-state rules, fully editable	Yes	Yes
Unlimited products	Yes	Yes
Compliance reports & CSV export	—	Yes
Tax audit trail	—	Yes
Priority support	—	Yes

Subscribing

In the Settings tab, click Choose Base or Choose Pro. You'll be redirected to BigCommerce's payment page. After completing payment, your plan activates automatically. Charges appear on your BigCommerce invoice.

Cancelling

Click Cancel Subscription in the Settings tab. VapeTax will continue working until the end of your billing period, then revert to returning $0 tax. Your checkout still works — customers can still complete orders — just without tax calculation.

Trial Expiry

If the 14-day free trial ends without subscribing, VapeTax returns $0 tax on all estimates. Subscribe anytime from the Settings tab to resume.

7. How Checkout Tax Works

Understanding the checkout flow helps with troubleshooting. Here's what happens when a customer checks out:

1. BigCommerce sends a tax estimate request to VapeTax with the cart items and shipping address.
2. VapeTax authenticates the request using store-specific credentials.
3. Each item's SKU is resolved against your synced product catalog.
4. The product type determines the system type: open_liquid = "open", closed_pod or closed_disposable = "closed", device or accessory = skipped entirely.
5. VapeTax looks up the excise tax rules for the shipping state, matching by system type.
6. Excise tax is calculated using the appropriate method and the product's volume, wholesale cost, retail price, or cartridge count.
7. Sales tax is calculated on the excise-inclusive amount (subtotal + excise tax).
8. The response is returned to BigCommerce within 4 seconds.

8. State Edge Cases

California — Stacked Tax

California applies two excise taxes simultaneously: 54.27% of wholesale cost plus 12.5% of retail price. VapeTax handles this with two separate rules for CA. Both are applied and summed automatically.

Maryland — Volume Threshold (5mL)

Products at or below 5mL are taxed at 60% of retail. Products above 5mL are taxed at 20% of retail. The volume field on your products must be set correctly for this to work.

Nebraska — Volume Threshold (3mL)

Products at or below 3mL are taxed at $0.05 per mL. Products above 3mL are taxed at 10% of retail.

Washington — Nicotine Split

Nicotine-containing products are taxed at 95% of wholesale cost. Non-nicotine products are taxed at a per-mL rate. The Contains Nicotine toggle on your products controls which rate applies.

Bifurcated States (10 States)

CT, GA, IN, KY, MD, NE, NH, NJ, NM, and RI tax open and closed systems at different rates. VapeTax has separate rules for each system type in these states. Your products must be classified as the correct type (open_liquid vs closed_pod/closed_disposable) for the right rate to apply.

9. When Tax Rates Change

State vape excise tax laws change periodically. When a rate changes:

1. Go to the Tax Rules tab.
2. Search for the state.
3. Click Edit and update the rate, method, or other fields.
4. Click Save. The new rate applies to the next checkout.

VapeTax does not automatically update rates after install. The default rules are a snapshot of Tax Foundation 2026 data. It's your responsibility to monitor rate changes and update your rules accordingly.

10. Tips & Best Practices

• Sync after adding products. Run a catalog sync whenever you add new products to BigCommerce so VapeTax can see them.
• Set volume on every liquid product. Even if your nexus states don't use per_ml, setting volume ensures accuracy if you expand to new states.
• Set wholesale cost accurately. Many high-tax states use pct_wholesale. Accurate costs mean accurate tax.
• Ignore non-vape items. Merchandise, gift cards, and non-vape accessories should be Ignored so they don't trigger unintended tax lookups.
• Test with multiple states. After setup, place test orders shipping to different states to verify your rules are working correctly.
• Use the Pro plan for filing. The compliance reports and CSV export make quarterly and annual filing much simpler.
• Keep your sales tax rates updated. VapeTax seeds sales tax rates as zeros. Fill in the rates for your nexus states.

Need help? Email support@vapetax.io and we'll get back to you within one business day.