RoasterPay: Understanding How Tax Calculation Works
In this article we will cover how to tax calculation works and how to process orders that have a mixed tax status.
In order to use our Tax Feature you have to have RoasterPay enabled on your account. Want to learn more about RoasterPay? Learn more here.
If you need to setup up tax on your account please see this article.
Overview:
When Is Tax Calculation Triggered?
When Is Tax Calculation NOT Triggered?
Orders With Mixed Taxes Statuses
Calculating Taxes
Taxes are calculated based on the combination of:
- Customer Tax Status
- Product Variant tax code
- Your tax registrations
- Customer Shipping address and the local taxes in that jurisdiction
When Do We Calculate Taxes?
Every time one of the trigger events happens, the system checks several conditions before deciding whether to calculate taxes. We only calculate taxes if all of the following are true:
- ✅ The account has taxes enabled.
- ✅ The account is using RoasterPay (our integrated payment system).
- ✅ The customer’s tax status is set to taxable.
- ✅ The order’s shipping address is in a state where sales tax is collected.
- ✅ The shipping address matches one of the account’s tax_registrations (i.e., the account is registered to collect tax in that state).
If any of these conditions are not met, we do not calculate taxes, and tax-related information will not be displayed for that order.
When Is Tax Calculation Triggered?
Whenever an order is submitted or updated, we check if it requires tax calculation. This happens in the following cases:
- When an order is submitted in the portal
- When an order is created via the app (Orders → New Order).
- When a submitted order is updated in the app.
- When a payment is created for an order.
- When an order is updated via a Shipstation shippings import (when the user has Live Shipping)
If any of these actions occur, we check whether the order needs tax calculation before proceeding.
When Is Tax Calculation NOT Triggered?
Tax calculation does not automatically run in the following cases:
- When a tax registration is added or removed.
- When a shipping address is updated (in the customer edit form, not within the order form).
- When a tax code is changed for any variant.
- When tax is enabled or disabled for the account.
If any of these changes occur, existing orders will not automatically recalculate taxes. However, tax will be recalculated the next time the order is updated—even if no actual changes are made.
How Tax Shows Up
Visibility of Tax Rates
To see what tax rate is used on the order you can hover over the icon next to the Tax line item on the order to see more details.
Visibility of Tax Code
To see what tax code is used on the order for each item you can hover over the tax badge next to the unit price.
Customer with Resale Tax Status:
Because customers with resale tax status may purchase a mix of taxable and non taxed items, we identify those customers' orders on the orders page as well. This helps to call out orders you may want to review the tax and make updates if needed. (see next section for more details on this)
Tax Calculations in the Portal
Taxes are calculated on orders placed the portal based on the criteria shared above. The taxes will not be calculated until the final order is placed.
- When items are added to the cart the tax will say TBD
- A customer will select "Checkout"
- The tax will still state TBD until they select "Place Order"
On the "Thank you" page, it will state the Tax calculated on the order
There are a few exceptions to when taxes are NOT calculated in the portal:
- The Customer must have a default delivery method with a known cost
- If there is no Default Delivery Method - the shipping field will say TBD and tax cannot be calculated yet
- If there is a shipping method with a LIVE or CUSTOM rate - the shipping field will say TBD and the tax cannot be calculated yet
- If a customer orders items with Mixed Tax Statuses
- You should NOT have them on Prepay terms as you need to review the order after it is placed and Manually update items that are taxed.
Orders With Mixed Taxes Statuses
Some customers may receive items with different tax statuses in the same order.
⚠️ Important: Customers who order mixed taxable items should not be on Prepay as you can only edit the tax status of items after an order has been created.
Example: Customer has Resale Tax Status and orders 1 bag of coffee (resale item) and 1 box of Fetco Filters (in house use taxable item).
Since this customer's tax status is set to Resale all items will be classified as Resale. You will need to manually edit the order to have the Fetco Filters taxed.
Follow the steps below to update:
- There are two ways to Identify orders that may have mixed tax status:
Option 1: If you don't have many products that would trigger tax, you can search on the fulfill page for specific items (example - Filters, or Cleaning supplies). That will then bring up the orders with those items and you can click on the invoice icon to open the invoice and make an update.
Option 2: On the orders page, you can identify resale tax status customers by the resale badge next to their order on your order screen.
How to Edit the Order:
- Select the order number
- Edit the order
- Locate which line items need to be taxed
- In the Tax Status column click the drop down choose the appropriate tax status then select update.
You should notice on the order a tax badge show up on the items being taxed.
What Happens When Tax Calculation Fails?
The impact of a failed tax calculation depends on where it was triggered.
- Portal: Order Submission
If tax calculation fails when submitting an order from the Portal, the contact will see an error message and won't be able to submit the order.
- Creating a Payment for an Order
If tax calculation fails when creating a payment, the user will see an error message and won't be able to proceed with the payment.
- Creating or Updating an Order in the App
If tax calculation fails after an order is created or updated, the user will see "Error" where the tax amount should be.
Any actions that were disabled while taxes were being calculated will remain disabled until the issue is fixed.
Hovering over the error will show a tooltip explaining why the calculation failed.If possible, the user can fix the issue and then manually trigger a recalculation from the tooltip.
Recalculating After an Error
- When an order is in an error state, simply updating the order will NOT trigger a recalculation.
- To retry, the user must click the button in the tooltip to manually launch the tax recalculation.