Using Numeral's Tax Engine on Stripe Invoices

This guide walks through connecting Stripe Invoicing to Numeral and ensuring accurate sales tax is applied to your invoices. If you send invoices to clients via Stripe Invoicing, you can use Numeral’s tax engine to apply accurate sales tax rates in the appropriate jurisdictions for your business.

---

​

Getting Started

1. Connect your Stripe account to your Numeral dashboard — in your Numeral dashboard, click Connections on the left-hand menu, then select Stripe.
2. You will be prompted to add the Numeral app to your Stripe account. Once installed, click continue to app settings — Stripe will present you with API keys. Copy these keys and enter them into Numeral.
   If you cannot see your entire restricted key, click roll key on Stripe, then roll API key. Stripe will require a verification process. Once verified, your full restricted key will be visible.
3. Once completed, you will see a dedicated Stripe section on your Connections page in Numeral. Status should show syncing with a green dot.

---

​

Timeline Considerations

If you are already using Stripe to apply tax rates to invoices, work with your Onboarding Manager to confirm your go-live date with Numeral. For example, if Numeral is taking over your existing sales tax registrations starting in August, meet with your Onboarding Manager on August 1 to turn off Stripe’s automatic tax calculator and turn on Numeral’s tax engine.

---

​

Updating and Confirming Configurations

During your go-live call, your Onboarding Manager will confirm that:

• Stripe’s automatic tax calculations are turned off
• Numeral’s tax engine is enabled
• Stripe’s tax behavior is set to exclusive

You can also check these settings yourself at any time:

---

​

Product Categorization

Correct product categorization is essential for accurate tax calculation. Product categories set in Stripe do not carry over to Numeral — categories must be set up directly within your Numeral account. During onboarding, your Onboarding Manager will help set up initial product categories in Numeral and show you how to manage them going forward. Numeral’s tax engine uses these categories to determine the correct taxability for each product.

​

Edit an Existing Product

1. Go to Developers → Products.
2. Click the Edit icon next to the product you want to update.
3. Search for and select the correct Product Category.
4. Save your changes.

​

Add a New Product

1. Navigate to Developers → Products → Create Product.
2. Enter the Product ID (this should match the Product ID in your sales platform).
3. Add the Product Name.
4. Select or type the appropriate Product Category.
5. Click Create Product to save.

---

​

Creating an Invoice within Stripe

​

Customers

• If your customer is not located in a state where you have an active registration set within Numeral, sales tax will not be applied.
• If your client has both a shipping and billing address, tax will default to the shipping address.
• If your client has a billing address but no shipping address, tax will be applied based on the billing address.

​

How Numeral determines the customer’s address

Numeral always starts with the shipping address on the invoice itself. If that address is complete, it is used to calculate tax. If the invoice’s shipping address is missing or incomplete, Numeral falls back through the following sources in order and uses the first complete address it finds. Any fields already present on the invoice’s shipping address are kept — only the missing fields are filled in from the fallback.

1. Customer shipping address on the invoice — the shipping address copied from the customer record onto the invoice when it was created.
2. Customer billing address — the current billing address on the Stripe customer.
3. Customer billing address on the invoice — the billing address as it was when the invoice was created. This is used when the customer record has been edited since the invoice was generated.
4. Payment method on the invoice — the billing address on the payment method used to pay the invoice.
5. Invoice custom fields — Numeral scans the invoice’s custom fields for a postal code and state.
6. Customer’s saved payment methods — the billing address on the customer’s saved payment method.

If none of the sources above provides a complete address:

• If the best available address has a country outside the US and Canada, Numeral uses that address as-is.
• If a US ZIP code was found in any of the sources, Numeral derives the state from the ZIP code and calculates tax based on it.
• If no usable address can be found at all, tax cannot be applied to the invoice.

State and province names are automatically normalized to their two-letter codes — for example, California becomes CA.

​

Items

When adding items, Numeral will only apply a tax rate if the item’s product category is taxable within your customer’s jurisdiction. Confirm product categories with your Numeral Onboarding Manager — product categories within Stripe do not apply.

​

Tax Rates

Numeral adds tax via webhook: when you save a draft invoice, Numeral receives a notification from Stripe, checks whether the customer is in a registered jurisdiction, and writes the correct tax rates back to the invoice. Stripe only allows invoices to be modified while they are in draft — once finalized, they can’t be changed. You must leave the invoice as a draft until Numeral has applied tax. To add tax to your invoices using Numeral’s Tax Engine in Stripe:

1. Add your customer and item information.
2. Save the invoice as a draft — do not finalize it yet.
3. Wait a few seconds for Numeral to apply tax (allow up to five minutes), then refresh your browser.
4. If any items are taxable, Numeral will have automatically added a tax line to the invoice preview.
5. Once the tax line appears, you can finalize and send the invoice.