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.

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:

1. When an order is submitted in the portal 
2. When an order is created via the app (Orders → New Order).
3. When a submitted order is updated in the app.
4. When a payment is created for an order.
5. 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:

1. 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
2. If a customer orders items with Mixed Tax Statuses
   1. 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.

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:

1. 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:

1. Select the order number
2. Edit the order
3. Locate which line items need to be taxed
4. 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.

1. 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.

2. 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.

3. 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.