Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 39 ยท Cart and Pricing

Taxes, Currency and Formatting

Work with WooCommerce tax classes, rates, wc_get_price_including_tax, wc_price and currency settings, and avoid rounding and multi-currency mistakes.

Tax and currency code looks harmless until the totals are one cent off, a customer in another country sees a price without VAT, or a "multi-currency" plugin charges the wrong amount. WooCommerce has a complete tax system and a set of price helpers. Most plugin bugs come from bypassing them: doing your own price * 1.2, printing a number with number_format, or storing a converted price as if it were the real one.

This lesson shows how WooCommerce models taxes, which functions give you the right number for display and for calculation, how wc_price() formats money, and where multi-currency setups go wrong. The business rules (who owes tax where, inclusive versus exclusive, rounding policy) are in Taxes in E-commerce and Currencies and Localization; this lesson is about the code. The WooCommerce code is read-only here. The runnable examples are plain PHP stand-ins that reproduce the arithmetic in integer cents.

How WooCommerce models tax

Taxes are configured in the admin and stored in tables, not in code:

  • Tax classes: a name that products carry. A fresh store has Standard, Reduced rate and Zero rate. WC_Tax::get_tax_classes() lists extra ones.
  • Rates: each row has a country, optional state, postcode and city matches, a percentage, a name, a priority, a compound flag and a shipping flag. Rates live in the wc_tax_rates table with their location lists in wc_tax_rate_locations.
  • Priority and compound: rates with the same priority are added together; a compound rate is calculated on top of the earlier amount (used in some countries). Rates with different priorities form separate steps.
  • Which address counts: a store setting chooses whether the customer's shipping address, billing address or the shop base decides the rates.

You almost never read the tables directly. Ask the API:

PHP
<?php
// Rates that apply to a class for the current customer (read-only).
$rates = WC_Tax::get_rates( $product->get_tax_class() );

// Compute the tax on an amount. The last argument says whether the amount already includes tax.
$taxes = WC_Tax::calc_tax( 100.00, $rates, false );  // array of tax amounts keyed by rate ID
$total_tax = array_sum( $taxes );

For products you rarely need WC_Tax at all, because the price helpers do the lookup.

The price helpers you should use

PHP
<?php
$product = wc_get_product( 123 );

// Price with tax added (or left alone if it already includes it), for calculations:
$gross = wc_get_price_including_tax( $product, array( 'qty' => 2 ) );

// Price without tax:
$net = wc_get_price_excluding_tax( $product, array( 'qty' => 2 ) );

// The price to SHOW, following the store's "display prices in the shop" setting:
$display = wc_get_price_to_display( $product );

Why three functions? Two store settings matter and they are independent:

  1. Prices entered with tax or without tax: how the numbers in the product fields are meant.
  2. Display prices in the shop and cart including or excluding tax.

A store can enter prices including VAT yet display them without it for business customers. wc_get_price_to_display() honors the display setting and the customer's tax exemption; wc_get_price_including_tax() always gives the gross price. Pick the one that matches what you are doing: display, or calculating something that must include tax. Never multiply a price by a rate yourself. The helpers account for the customer's location, the tax class, compound rates, tax-exempt customers and the entered-with-tax rule.

When you must influence rates, filter them rather than replacing the calculation: woocommerce_matched_rates lets you adjust the rates matched for an address, and woocommerce_product_get_tax_class lets you change the class a product reports. Keep such code small; tax rules are a legal matter and an external tax service integration is usually safer than custom rules.

flowchart LR
    A["Entered price<br/>(with or without tax)"] --> B["Tax class of product"]
    B --> C["Rates matched for<br/>customer address"]
    C --> D["wc_get_price_including_tax /<br/>excluding_tax"]
    D --> E["wc_get_price_to_display<br/>(shop and cart setting)"]
    E --> F["wc_price formats the string"]

The display setting only changes the last steps; calculation helpers stay tax-aware.

Rounding

WooCommerce can round tax per line (the default: tax is rounded for each line and the results are added) or at the subtotal (the unrounded line taxes are added and the sum is rounded once). The setting is "Round tax at subtotal level, instead of rounding per line". The two give different totals on some carts, and there is no universally correct answer: it depends on the country and on what your invoices must show. The important points for plugin authors:

  • Never recalculate totals with your own rounding and compare them with WooCommerce's. Read totals from the cart or the order (get_total_tax(), get_total()).
  • If you add a fee or a discount line, tell WooCommerce whether it is taxable and let it compute the tax (Dynamic Pricing, Fees and Discounts).
  • Tests that compare totals should state the rounding mode they assume.

The first stand-in below shows the difference concretely.

Formatting money with wc_price

wc_price( $amount, $args ) returns an HTML string, not plain text: it wraps the amount in <span class="woocommerce-Price-amount amount"> and the symbol in its own span. It uses the store's currency, decimal and thousand separators, number of decimals and the symbol position setting:

PHP
<?php
echo wc_price( 1234.5 );                                   // "$1,234.50" wrapped in spans
echo wc_price( 20, array( 'currency' => 'EUR' ) );         // override the currency for this call
echo wc_price( 20, array( 'decimals' => 0 ) );             // override the decimals

// Plain text (for emails in plain format, JSON, logs):
$plain = wp_strip_all_tags( wc_price( 1234.5 ) );

Some rules to keep you out of trouble:

  • Use wc_price() for output and wc_format_decimal() for storing and comparing numbers. Never store the formatted string.
  • Print the result as it is; it is already safe HTML. Do not run it through esc_html() or the markup will show as text.
  • The knobs are filters: wc_price_args (arguments for each call), woocommerce_price_format (position pattern of symbol and number), woocommerce_currency_symbol and woocommerce_currency. A currency switcher plugin typically hooks woocommerce_currency and the price filters.
  • get_woocommerce_currency() returns the active currency code; orders store their own currency ($order->get_currency()), which can differ from the store's current setting later. Always format an order's amounts with the order's currency: wc_price( $order->get_total(), array( 'currency' => $order->get_currency() ) ).

Multi-currency pitfalls

WooCommerce itself has one store currency. Multi-currency is added by plugins, and the same few mistakes appear again and again:

  1. Converting at the wrong place. Converting each line and summing is not the same as converting the total. Decide where conversion happens (usually per unit price, once) and keep it there.
  2. Charging in a different currency than the one shown. The amount sent to the gateway must be the order total in the order currency. Check what your gateway expects.
  3. Rates that change mid-session. Lock the rate when the cart is created or when the order is placed, and store it on the order, so refunds can be computed later.
  4. Zero-decimal currencies. Yen and similar currencies have no minor unit. Code that assumes "multiply by 100" breaks. Use wc_get_price_decimals() and the gateway's rules for the smallest unit.
  5. Caches. Prices that vary by currency must not be printed into cached pages without a variation key. See the caching section of Dynamic Pricing, Fees and Discounts.

Runnable stand-ins

These run in plain PHP. They are not WooCommerce: they reproduce the arithmetic so you can see numbers change when the rounding rule changes.

PHP Per-line versus subtotal tax rounding

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

On the five 0.95 lines, per-line rounding sees 0.095 tax on each line and rounds it up five times, so the total is 2 cents higher than rounding once. The big single item shows no difference, which is why the problem hides in tests that use only one product. The inclusive-price part (taking tax out of gross prices) happens to agree at 2.50 for these numbers; the same choice applies there, but a different basket could split the two results apart.

The second stand-in formats money the way wc_price() does, from a currency settings array, and shows the multi-currency order-of-conversion trap.

PHP A wc_price stand-in and the conversion trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The currency settings change only the text. The conversion example shows a one-cent gap that appears when the same money is converted at two different steps; a store must choose one step and document it, because the order total, the invoice and the gateway amount have to agree.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You need the price to print in the shop, respecting the store's "display prices including or excluding tax" setting. Which function fits?

    wc_get_price_to_display() follows the display setting and customer exemptions. The including-tax helper always returns the gross price, and multiplying by a rate yourself ignores the customer's location and tax class.
  2. 2. Why should you not pass the result of wc_price() through esc_html()?

    wc_price() returns HTML with price spans. Output it as is, or strip the tags with wp_strip_all_tags() when you need plain text.
  3. 3. What is the practical difference between per-line and subtotal tax rounding?

    Rounding each line before adding is not the same as adding first and rounding once. A single large line hides the difference, a basket of small lines shows it.
  4. 4. Which currency should you use to format the amounts of an existing order?

    The store currency can change after the order was placed. The order stores the currency it was charged in, and formatting must use it.

Summary

  • Tax classes, rates, priority and compound flags are data; use WC_Tax and the price helpers instead of your own math.
  • wc_get_price_to_display() is for showing prices, wc_get_price_including_tax() and wc_get_price_excluding_tax() are for calculations.
  • Rounding per line and at the subtotal can differ by cents; read totals from WooCommerce and test with baskets of small lines.
  • wc_price() returns HTML; format with the order's currency for existing orders and store numbers with wc_format_decimal().
  • In multi-currency setups, convert in one agreed place, lock the rate on the order, and respect zero-decimal currencies.
  • The stand-ins show arithmetic only; the real tax lookup needs WooCommerce and its settings.

Next: Orders and High-Performance Order Storage