Taxes, Coupons, Currencies and i18n

WooCommerce computes tax from four inputs.

WC_Tax::find_rates() receives the location and the class, looks the rows up in the woocommerce_tax_rates table (with its woocommerce_tax_rate_locations helper table for postcode and city lists), and returns the matching rates keyed by rate id. The result is cached in the taxes object-cache group, and the filter woocommerce_find_rates can change it.

Taxes are calculated only when the switch behind woocommerce_calc_taxes (General tab, Enable tax rates and calculations) is on; the Tax tab appears after that. WooCommerce > Settings > Tax then holds the options below. The "Value on the test store" column was read with wp option get and shows the defaults of a store configured with WP-CLI.

Source: WooCommerce documentation: Setting up taxes in WooCommerce

The first two are the ones that cause trouble. Prices entered with tax tells WooCommerce how to read the price stored on the product: as the net price (tax is added on top) or as the gross price (tax is inside). Changing it later does not rewrite products, it changes the meaning of every stored price, so decide it before importing the catalogue. Calculate tax based on chooses the location. For a shop that sells within one country the base address is enough; for cross-border sales the shipping address is the default, and the billing address is the alternative for services and digital goods taxed where the buyer lives.

The 11.2.0 changelog (2026-10-07) lists a fix that initialises new orders with the store’s current tax entry mode and preserves the saved order values when the store setting changes, so a historic order is not reinterpreted. An order exposes its mode as WC_Order::get_prices_include_tax() (on the test store order 15 reports exclusive).

A rate is one row. The columns, from SHOW COLUMNS FROM wp_woocommerce_tax_rates on 11.2.1:

Postcodes and cities are stored in woocommerce_tax_rate_locations and accept lists separated by semicolons, ranges written as 90210...99000 and wildcards written as NR*. The rate table also exists as CSV: the admin page offers Import CSV and Export CSV with ten columns (country code, state code, ZIP/postcode, city, rate %, tax name, priority, compound, shipping, tax class), where an empty tax class means Standard.

Compound and priority are the parts people misread, so the arithmetic is worth seeing once. The test below passes two rates straight to the calculator: a regular 10% rate and a compound 5% rate. The compound rate is taken on the price plus the first tax, so on 100.00 the second tax is 5.50, not 5.00.

Output on the test store (run with wp eval):

Source: WooCommerce code reference: WC_Tax

The inclusive call returns the same two amounts for a gross price of 115.50, which shows that calc_inclusive_tax() works backwards through the compound rates first and then through the regular ones.

Rates are normally typed into the admin, but a plugin that ships with a store (or a migration script) can create the class and its rows. WC_Tax::create_tax_class() returns the class as an array with slug and name, and WC_Tax::_insert_tax_rate() inserts one row; both are internal-use APIs of the tax settings screen, which is why _insert_tax_rate() has a leading underscore, and both clear the taxes cache group. The activation routine in the plugin below installs Pocket Coffee Beans with a 10% rate for Spain and a 7% rate for Germany. The rates are illustrative: the real VAT treatment of coffee in each country must come from a tax adviser, not from this page.

The whole plugin is listed in one piece in The Pocket Coffee Taxes plugin; the sections that follow refer to its functions. After wp plugin activate pocket-coffee-taxes:

Source: WooCommerce docs: WC-CLI overview

A product that uses the class is created with --tax_status and --tax_class (the class is addressed by slug; the product id 23 below is the id this store assigned):

Source: WooCommerce REST API documentation: create a product

Asking the calculator directly shows the location matching. On the test store (base Madrid):

France has no row in this class, so a French customer would pay no tax on these beans. That silent zero is the most common configuration mistake: when a class is missing a country, WooCommerce does not fall back to the Standard class, it simply finds nothing.

Order totals confirm the same arithmetic. The script creates an order for two bags at 9.90 net, once with a Madrid address and once with a Berlin address, calls calculate_totals() and deletes the orders afterwards:

Source: WooCommerce docs: CRUD objects

Shipping was not added, so the totals are for beans only. The same calculation through the shopper API, with the 450 shipping flat rate of the test store, returned total_items 1980, total_items_tax 198, total_shipping 450, total_shipping_tax 0 and tax_lines [{"name":"IVA 10%","price":"198","rate":"10%"}]: the Store API reports amounts in minor units (cents), and shipping carried no tax because shipping tax needs a rate whose Shipping flag is on in the resolved class (the rates of the class were created with Shipping off).

A very common European setup is "prices include tax". Because the Pocket Coffee test store has the setting at no, the next experiment forces it for one script with a pre_option_ filter, so no stored setting changes. The product’s price of 9.90 is now treated as gross. A customer in the store’s own country pays exactly the shelf price; a customer in another tax zone gets the base tax removed and the local tax added:

Source: WooCommerce documentation: Setting up taxes in WooCommerce

The German customer pays 9.63, not 9.90: 9.90 minus 10% Spanish tax is 9.00, plus 7% German tax is 9.63. This price adjustment is on by default; the filter woocommerce_adjust_non_base_location_prices (return false) switches it off for the cart so that the price stays fixed at the shelf value and the tax is carved out of it at the local rate. EU stores that must show one fixed consumer price in every member state often turn it off, and then take the lower or higher margin knowingly.

Maintaining rate tables by hand is workable for a few countries. For many jurisdictions Woo offers WooCommerce Tax (previously part of WooCommerce Shipping and Tax), an extension connected to a WordPress.com account that calculates rates automatically and switches the manual options off while it is on. It could not be installed in the test stack because it needs an account, so only its documented behaviour is described here. The Woo documentation also links a separate guide for EU VAT rates on digital products, because the place-of-supply rules for digital goods differ from those for physical goods. Core WooCommerce has no one-stop-shop reporting, no VAT-number checks and no reverse-charge invoices; those are extension or accounting-system territory.

Source: WooCommerce documentation: WooCommerce Tax

Source: WooCommerce code reference: WC_Tax

The wp wc tax and wp wc tax_class command groups call the REST controllers, so they need --user with an administrator. Creating and removing a French row on the test store:

The REST equivalents are GET /wp-json/wc/v3/taxes?class=pocket-coffee-beans, POST /wp-json/wc/v3/taxes, GET /wp-json/wc/v3/taxes/classes and POST /wp-json/wc/v3/taxes/classes; with consumer key and secret over HTTPS the first returned the two rows (1, ES, 10.0000, IVA 10%) and (2, DE, 7.0000, MwSt 7%). Keys are written as ck_xxxxxxxx and cs_xxxxxxxx in documentation; never put real ones in a repository.

Source: WooCommerce REST API documentation: tax rates

A coupon is a custom post (post type shop_coupon, stored with the WordPress post tables even when orders use HPOS) read and written through WC_Coupon. A shop enables coupons with WooCommerce > Settings > General > Enable coupons (woocommerce_enable_coupons, default yes); with it off, wc_coupons_enabled() is false and no coupon field is shown. The sibling option Calculate coupon discounts sequentially (woocommerce_calc_discounts_sequentially, default no) applies the second coupon to the price already reduced by the first one instead of to the original price; an 11.2.0 fix made sequential coupons with equal priority calculate in the order they were applied. WooCommerce does not apply coupons automatically; the customer (or code) must apply one.

There are three discount types, returned by wc_get_coupon_types() and extensible with woocommerce_coupon_discount_types: percent (percentage discount), fixed_cart (a fixed amount shared across the cart) and fixed_product (a fixed amount off each unit of the matching products). Coupons reduce product prices before tax, tax is recalculated on the reduced amount, and shipping is only affected by a coupon with Allow free shipping.

The data properties of WC_Coupon and their admin labels are:

Source: WooCommerce documentation: Coupon management

The brand restrictions of the admin screen (Product brands and Exclude brands) are implemented by WC_Brands_Coupons, which hooks the same woocommerce_coupon_is_valid and woocommerce_coupon_error filters shown below.

Pocket Coffee has one standing discount, 10% off beans for members. The coupon is created through the CRUD class: a percent coupon, limited to the Beans category (term id 16 in the test store), five uses per customer, valid until the end of 2027.

Source: WooCommerce code reference: WC_Coupon

The same data can be created from WP-CLI and REST; both were run on the test store, and the second coupon below was removed afterwards:

The REST response echoed "amount":"2.00", "discount_type":"fixed_product", "product_ids":[22], "email_restrictions":["*@example.test"] and "exclude_sale_items":true. The wp wc shop_coupon get output for the first one listed amount 5.00, minimum_amount 30.00, usage_limit 100, date_expires 2027-12-31T00:00:00 and free_shipping false.

Source: WooCommerce REST API documentation: coupons

When a code is applied, WC_Discounts::is_coupon_valid() runs the checks in a fixed order and stops at the first failure. Each failure is an exception carrying a numeric code, and WC_Coupon::get_coupon_error() maps the code to a message.

The extension point is the filter woocommerce_coupon_is_valid, called with the current result, the WC_Coupon and the WC_Discounts object; a rule rejects a coupon by throwing an Exception whose message is shown to the customer and whose code selects the error. WooCommerce 11.1.0 added finer filters for the individual restriction checks, renamed in the same release to the woocommerce_coupon_is_valid_for_* family: woocommerce_coupon_is_valid_for_product_ids, woocommerce_coupon_is_valid_for_product_categories, woocommerce_coupon_is_valid_for_sale_items, woocommerce_coupon_is_valid_for_excluded_items, woocommerce_coupon_is_valid_for_excluded_product_ids and woocommerce_coupon_is_valid_for_excluded_product_categories (true means valid), alongside the older woocommerce_coupon_validate_expiry_date, woocommerce_coupon_validate_minimum_amount, woocommerce_coupon_validate_maximum_amount and woocommerce_coupon_validate_user_usage_limit. Use the narrow filter when one check needs changing, and the general one for a new business rule such as "members only".

The plugin implements that rule: only users whose user meta _coffee_club is set may use coffeeclub10. It was exercised through three paths. First through WC_Order::apply_coupon() as a guest, as a logged-in user without the flag, and as the flagged member (Ada, ada@example.test):

The member’s order shows the "before tax" rule at work: the 10% discount is 1.98, the tax is recomputed on 17.82 and comes to 1.78 (the 0.2 discount_tax is the tax that the discount removed), and the total is 19.60. Second, through the Store API with a Cart-Token obtained from GET /wp-json/wc/store/v1/cart, where applying the coupon as a guest returned HTTP 400:

The second line is the answer for a code that does not exist. Third, under the Spanish locale the error text is translated (see Translations), which was checked by calling apply_coupon() inside switch_to_locale( 'es_ES' ): the message came back as Este cupón es solo para miembros del Coffee Club. The Store API endpoints involved are POST /cart/apply-coupon and POST /cart/remove-coupon with a JSON body {"code":"..."}, and GET /cart/coupons; the Cart and Checkout blocks call the same ones.

Source: WooCommerce docs: Store API

Two newer hooks help integrations: woocommerce_order_applied_coupon and, since 11.2.0, woocommerce_order_removed_coupon (parity with the cart), and the JavaScript events errored_coupon and errored_coupon_in_checkout fired on the classic cart and checkout when a coupon fails. A classic-checkout trick from older cookbooks, hiding the coupon form with a woocommerce_coupons_enabled filter, still works in the sense that the filter turns coupons off entirely, but custom discount logic for the blocks belongs in coupon filters and Store API extensions, not in template edits.

Source: WooCommerce code reference: WC_Discounts

A WooCommerce store has exactly one currency (woocommerce_currency, here EUR), and a few format settings under WooCommerce > Settings > General > Currency options: woocommerce_currency_pos (left, right, left_space, right_space; left on the test store), woocommerce_price_thousand_sep (,), woocommerce_price_decimal_sep (.) and woocommerce_price_num_decimals (2). The list of 164 currencies in 11.2.1 comes from the file i18n/currencies.php through get_woocommerce_currencies(); the filter woocommerce_currencies can extend it, and woocommerce_currency can change the active code at run time. Symbols come from get_woocommerce_currency_symbol() and the filter woocommerce_currency_symbol.

Formatting goes through wc_price( $amount, $args ). Its $args array overrides currency, decimal_separator, thousand_separator, decimals and price_format for one call, and the HTML result carries the classes woocommerce-Price-amount and woocommerce-Price-currencySymbol that themes and tests rely on:

Output, tags shortened to the text (the symbol of EUR is the entity € and the dollar sign $):

Source: WooCommerce code reference: formatting functions

Several consequences are easy to miss.

A shop that sells loyalty points or a local currency registers it with two filters. The Pocket Coffee plugin adds a currency PCB ("Pocket Coffee points") with the symbol PCB followed by a space. Register the filter when the plugin loads, because the currency list is cached on first use:

That line is the output of wc_price( 120, array( 'currency' => 'PCB', 'decimals' => 0 ) ) with tags removed, the registered name, and the new total of known currencies (164 plus one).

Pocket Coffee shows dollars to customers outside the euro area. The plugin does this display-only: the helper pocket_coffee_taxes_usd() multiplies the displayed amount by a fixed rate and formats it with wc_price( ..., array( 'currency' => 'USD' ) ), and the shortcode [pocket_coffee_usd id="23"] prints both prices. The order is still created and paid in euros. With a rate of 1.08 on the 9.90 beans:

(markup removed). A fixed rate in code is a demonstration; a real shop reads a rate from a service or option and says clearly that the shown figure is approximate.

All interface text in WooCommerce core and in extensions is written with the WordPress gettext functions (__(), _e(), _n(), _x() and esc_html__()) and a text domain, woocommerce for the core plugin. Translators work on translate.wordpress.org; when a locale of a plugin reaches 90 percent for the stable version, WordPress offers it as a language pack that Dashboard > Updates > Update Translations (or wp language plugin update --all) downloads. On the test store:

The pack for WooCommerce lands in wp-content/languages/plugins/ as woocommerce-es_ES.mo and woocommerce-es_ES.po, together with woocommerce-es_ES.l10n.php (the PHP-array format WordPress loads faster) and a set of hash-named JSON files for the script translations of the block editor and the Cart and Checkout blocks (wp_set_script_translations() reads them). With the pack in place, switching locale in code translates WooCommerce itself:

Source: WP-CLI handbook: wp language core

switch_to_locale() is the WordPress function that renders text in another locale for one operation, and what the Pocket Coffee examples below use to compare Spanish and English output without changing the site language (the option WPLANG stayed en_US). It only switches to locales that are installed, which is why the language pack was installed first; on the test store the first attempt, before installing the pack, silently stayed in en_US.

The loader in WooCommerce::load_plugin_textdomain() supports a custom location besides the standard one. If WP_LANG_DIR/woocommerce/woocommerce-LOCALE.mo exists it is loaded in addition to the language pack, and its strings win; that is the upgrade-safe place for a merchant’s own wording (wp-content/languages/woocommerce/woocommerce-es_ES.mo). The filter plugin_locale changes the locale WooCommerce asks for. The merchant documentation lists the other options: a manually downloaded .mo for locales below 90 percent, Loco Translate with its Custom folder, PoEdit starting from woocommerce.pot in i18n/languages/, and string-replacement plugins.

Source: WooCommerce documentation: Localization and translation

A plugin follows the WordPress standard: a Text Domain and Domain Path in the header, calls to the gettext functions with that domain, a .pot template, one .po per language compiled to .mo, and a call to load_plugin_textdomain(). WordPress 6.7 and later warn when a text domain is loaded before the init action, so the Pocket Coffee plugin loads it on init (see the listing). Plugins hosted on WordPress.org get language packs automatically and do not need load_plugin_textdomain() at all; the plugin loads it explicitly because it is distributed with the store.

The strings of the plugin are plain, one with a placeholder and one with plural forms:

The template was generated and the Spanish catalogue compiled with WP-CLI:

The generated .pot (header trimmed) lists the four extracted messages with their references and the translators: comments:

The Spanish catalogue pocket-coffee-taxes-es_ES.po (header with Language: es_ES and Plural-Forms: nplurals=2; plural=(n != 1);) translates three of them:

Running the plural helper and the shortcode in both locales:

The wp i18n make-php command converts .po files to the .l10n.php format and wp i18n make-json extracts the JavaScript strings of a .po into the JSON files that wp_set_script_translations() loads; wp i18n update-po merges a new .pot into existing catalogues. They were not run for this plugin, which has no JavaScript.

Source: WordPress Plugin Handbook: How to internationalize your plugin

Source: WP-CLI handbook: wp i18n make-pot

Gettext translates code. Products, categories, attributes, pages and the shop’s own notices are content stored in the database, and translating them takes a multilingual plugin. They differ in how they store translations.

Source: WordPress.org: Polylang

Source: WordPress.org: TranslatePress

None of them was installed in the test store, so the table reports each vendor’s documentation, not an experiment. For Pocket Coffee the setup is the same with every plugin: Spanish as default language with its own URL root, English as a second language, product titles and descriptions translated, the Beans category and the origin attribute terms translated, the Cart, Checkout, My Account and Shop pages translated and linked as translations of each other, and the language switcher in the header. Check that the coupon error, tax names (the Tax name column, IVA 10% and MwSt 7%, is stored once and is not translated by gettext; multilingual plugins that offer string translation can translate it) and email texts are covered, and test checkout in both languages with the same cart.

Search engines need each language on its own URL with hreflang links; full-page caches must vary by language cookie or URL. The caching page of the performance guide lists the cookies that must bypass the cache.