Skip to main content
Numeral Tax installs into Saleor as a tax app. Saleor asks Numeral for tax every time a checkout or order is priced, so the shopper sees the exact tax from the first address they enter. When an order is confirmed, Numeral records it for filing; cancellations and refunds are reversed automatically. There is nothing to deploy on your side: the app runs on Numeral’s infrastructure and connects to your Saleor instance through Saleor’s app framework.

​
Requirements

​
Connect your store

  1. In the Numeral dashboard, open Connections and choose Saleor.
  2. Tick Sandbox store if this is a Saleor Cloud sandbox or a staging environment. Sandbox stores calculate in Numeral test mode and are never filed.
  3. Click Generate install link. Numeral shows a manifest URL that is unique to your account. Treat it like a password.

​
2. Install the app in Saleor

  1. In Saleor Dashboard, go to Apps and choose Install external app.
  2. Paste the manifest URL and click Install.
  3. Approve the permissions. Numeral asks for HANDLE_TAXES (to calculate tax) and MANAGE_ORDERS (to receive order events and write Numeral ids onto orders).
The Numeral dashboard updates on its own once the install completes and shows the Saleor domain it is connected to.

​
3. Make Numeral the tax calculator for your channels

  1. In Saleor Dashboard, go to Configuration then Taxes.
  2. For each channel, set the tax calculation strategy to the Numeral Tax app.
  3. Choose whether your prices are entered with tax included. Numeral honours this setting: tax is added on top of exclusive prices and extracted from inclusive ones.
Tax now flows through Numeral for every checkout and order in those channels.

​
What Numeral calculates

  • Every line is taxed by its product’s category and the shipping address. Lines with Charge taxes switched off in Saleor are returned at a zero rate.
  • Shipping is taxed as its own line, following the destination’s rules for delivery charges, whenever the order ships physical goods, including free shipping (some jurisdictions charge a delivery fee regardless of the shipping price). A digital-only order never picks up a delivery fee.
  • Discounts. Line-level discounts are already in Saleor’s line prices. Order-level discounts are split across the lines in proportion to their totals, and shipping vouchers reduce the shipping price, before tax is calculated.
  • Before an address is entered, prices are shown without tax. Saleor re-asks Numeral as soon as the address changes.

​
Product categories

Numeral taxes each product by its category. Pick one of these, in order of precedence:
  1. Add a metadata entry on the product with key numeral_product_category and a Numeral product category code as the value (for example CLOTHING or SOFTWARE_SAAS).
  2. Name the product’s Saleor tax class with a Numeral category code. Any tax class whose name is a Numeral category code is used as that category; other tax-class names are ignored.
  3. Otherwise Numeral resolves the product by its SKU against the products synced to your Numeral account, falling back to your account’s default category.
The full list of category codes is in the product categories reference.

​
Exempt customers

Attach the Numeral customer id of an exempt customer to a checkout or order as metadata with key numeral_customer_id. Numeral applies that customer’s exemption certificates from Exemption Certificate Management. Without it, Numeral resolves the Saleor user id against your synced customers.

​
Order recording

After recording, Numeral writes numeral_calculation_id, numeral_transaction_id and, when applicable, numeral_refund_id into the order’s metadata so you can trace a filing line back to the Saleor order.

​
Troubleshooting

The install fails with “install link is not valid”. Generate a fresh link from the Numeral dashboard. Links are tied to your Numeral account. Saleor says the instance is already connected. The Saleor instance is registered to a different Numeral account or store. Disconnect it there first. Tax shows as zero at checkout. Check that the channel’s tax calculation strategy is set to the Numeral Tax app, that a shipping address with a country is set, and that the products’ Charge taxes flag is on. Prices look wrong by the tax amount. Confirm the channel’s “prices entered with tax” setting matches how your catalog is priced.

​
Limits

  • One Saleor instance per Numeral store connection.
  • Saleor’s per-checkout tax exemption flag is not read; use numeral_customer_id for exempt customers.
  • Refund allocation is proportional across lines; Saleor’s granted-refund line detail is not consulted.