> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Saleor

> Real-time sales tax calculation at checkout for Saleor, with automatic order recording.

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

| Requirement | Detail |
| - | - |
| Saleor | 3.23 or newer (Saleor Cloud or self-hosted, reachable from the internet over https) |
| Saleor permissions | You must be able to install apps and edit channel tax configuration |
| Numeral | An account at [dashboard.numeralhq.com](https://dashboard.numeralhq.com) |

## Connect your store

### 1. Generate an install link in Numeral

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](https://docs.numeral.com/essentials/product-categories.md).

### 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

| Saleor event | What Numeral does |
| - | - |
| Order confirmed | Records a transaction using the calculation the shopper saw. If the order changed after the last calculation, Numeral recalculates from the confirmed order first. |
| Order cancelled | Fully reverses the transaction. |
| Order refunded | Reverses the amount refunded since the last refund event, across what remains of the order's lines and shipping. A full refund reverses whatever is left of the transaction. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.