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

# Shipping Rates, Tax Configuration, and VAT Settings

> Configure shipping and tax in Site Store Pro — flat-rate range syntax, real-time carrier rates, US/CA sales tax, international VAT, and VAT-inclusive pricing.

All shipping, tax, and currency settings for your store are managed from the Shipping & Taxes Console at `/admin/ecommerce/shipping`. From here you can define flat-rate tiers using range syntax, configure real-time carrier integrations, set US state and Canadian provincial tax rates, manage international VAT, and control how tax is applied per product variant. Non-US/CA merchants can also activate VAT-inclusive storefront pricing from the Merchant Location section.

## Shipping & Taxes Console

```http theme={null}
GET /admin/ecommerce/shipping
```

All shipping, tax, currency, and merchant location settings are managed from the **Shipping & Taxes Console**.

***

## Shipping Configuration

### Flat-Rate Shipping

#### Dynamic Grid Flat-Rate

Define price tiers based on **weight**, **subtotal**, or **item count** using range syntax:

```text theme={null}
Min-Max=Price,Other=Default
```

**Examples:**

| Scenario            | Syntax                             |
| ------------------- | ---------------------------------- |
| Weight-based (lbs)  | `0-5=5.00,5-10=8.00,Other=15.00`   |
| Subtotal-based (\$) | `0-50=9.99,50-100=6.99,Other=0.00` |
| Item count          | `1-3=4.99,3-6=7.99,Other=12.99`    |

* **Min-Max ranges** define the lower and upper bounds of each tier (lower-inclusive, upper-exclusive).
* **`Other`** is the fallback price for any value that doesn't match a defined range.

#### Custom Flat-Rate Options

Pre-defined selectable shipping options for domestic and international destinations:

| Option              | Notes                                           |
| ------------------- | ----------------------------------------------- |
| Standard Ground     | Default economy option                          |
| Express 2-Day       | Two business-day delivery                       |
| Overnight Air       | Next business-day delivery                      |
| Local Pickup (Free) | No shipping charge; customer collects in person |

#### Free Shipping via Coupon

When a coupon has `free_shipping = true`, all shipping charges are waived at checkout regardless of the shipping method selected.

***

### Real-Time Carrier Rates

Real-time rates are provided by carrier plugins. See the [Plugins documentation](/plugins) for setup instructions.

| Carrier | Plugin Required   |
| ------- | ----------------- |
| FedEx   | FedEx Rate Plugin |
| UPS     | UPS Rate Plugin   |
| USPS    | USPS Rate Plugin  |

**Merging behavior:** Live carrier rates are merged with any configured flat-rate options and presented to the customer sorted **low-to-high**.

<Info>
  **Graceful degradation:** If a carrier API is unreachable at checkout time, that carrier's rates are silently skipped. Checkout is never blocked — remaining flat-rate and other carrier options continue to display normally.
</Info>

***

## Tax Configuration

### US Sales Tax & Canadian Provincial VAT

* Configure **state-by-state sales tax rates** for all US states.
* Configure **provincial VAT** for all Canadian provinces.

Rates are applied based on the shipping destination address entered at checkout.

### International Country VAT

Custom VAT rates can be defined per country. Country-level VAT is charged when:

1. The `charge_vat` toggle is active in the Shipping & Taxes Console.
2. The order's destination country matches a configured VAT rate.

***

### Merchant-Location-Aware VAT Engine

When the configured **Merchant Country** is **not** US or Canada, Site Store Pro activates **VAT-inclusive pricing mode**.

#### How It Works

| Customer Location           | Price Shown   | Calculation                  |
| --------------------------- | ------------- | ---------------------------- |
| Same country as merchant    | VAT-inclusive | `net_price × (1 + rate/100)` |
| US or Canada (cross-border) | VAT-exclusive | `net_price` only             |

All storefront prices are displayed **including VAT** for domestic visitors. Cross-border US/CA buyers see the net price with VAT stripped at checkout.

**UK merchant example:**

|                   | Value                  |
| ----------------- | ---------------------- |
| Product stored as | £16.67 (ex-VAT)        |
| UK buyer sees     | £20.00 (incl. 20% VAT) |
| US buyer sees     | \$16.67 (VAT stripped) |

<Warning>
  When you change the Merchant Country to a non-US/CA country, a warning is displayed in the admin confirming that VAT-inclusive pricing mode will activate.
</Warning>

***

### Dynamic Tax Labels

The tax line label shown on invoices, cart, and checkout adapts based on the customer's country:

| Customer Country    | Tax Label |
| ------------------- | --------- |
| United States       | Sales Tax |
| Canada              | GST/HST   |
| All other countries | VAT       |

***

## Per-Item Taxability (`charge_tax`)

Tax applicability is evaluated per line item using an **OR rule**:

```text theme={null}
item_taxable = 1  if  (variant.charge_tax = 1)
                  OR  (any product_field.charge_tax = 1 for this product)
```

Both `variant.charge_tax` **and** all `product_field.charge_tax` values must be `0` for an item to be tax-exempt.

### Tax Calculation

```text theme={null}
taxableSubtotal = Σ (item.final_price × item.qty)
                  for all items where item_taxable = 1
```

Sales tax (or VAT) is then applied only to `taxableSubtotal`.

### Taxability Propagation Stages

| Stage                         | Table / Field                    | Default               |
| ----------------------------- | -------------------------------- | --------------------- |
| Product variant configuration | `product_variants.charge_tax`    | Toggle **ON**         |
| Product field configuration   | `product_fields.charge_tax`      | Toggle **ON**         |
| Add-to-cart event             | `shopping_cart_log.item_taxable` | Computed from OR rule |
| Order placement               | `order_details.item_taxable`     | Permanently recorded  |

<Note>
  The `item_taxable` value is locked at the time of order placement. Subsequent changes to product variant or field `charge_tax` settings do not retroactively alter existing orders.
</Note>

***

## Merchant Location & Currency Settings

Located in the **Merchant Location & Currency** section of `/admin/ecommerce/shipping`.

### Merchant Country

Determines whether VAT-inclusive pricing mode is activated. A confirmation warning is displayed when selecting any non-US/CA country.

### Currency Settings

| Field           | Description                         | Example                           |
| --------------- | ----------------------------------- | --------------------------------- |
| Currency Code   | 3-character ISO 4217 code           | `USD`, `GBP`, `EUR`, `AUD`, `CAD` |
| Currency Symbol | Prefix-positioned before all prices | `£19.99`, `€24.00`                |

The currency symbol defaults to `$`. It propagates throughout the entire storefront:

<CardGroup cols={3}>
  <Card title="Shop Catalog" icon="store" />

  <Card title="Product Details" icon="tag" />

  <Card title="Cart" icon="cart-shopping" />

  <Card title="Slide-Out Cart Drawer" icon="sidebar" />

  <Card title="Order Review" icon="list-check" />

  <Card title="Checkout Success" icon="circle-check" />

  <Card title="Order Confirmation Email" icon="envelope" />
</CardGroup>

***

## Order-Level Handling Charges

Handling surcharges can be configured to trigger automatically based on combinations of:

| Trigger Condition    | Field                             |
| -------------------- | --------------------------------- |
| Order subtotal range | Min and/or max subtotal threshold |
| Minimum total weight | Cart weight in configured units   |
| Minimum item count   | Total quantity of items in cart   |

When all active trigger conditions are satisfied simultaneously, the surcharge is added to the order total.