=== Kargadann's PLN Price Converter for WooCommerce ===
Contributors: kargadann
Tags: currency converter, exchange rates, currency switcher, poland, pln
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.2
Stable tag: 1.0.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Shows informational prices in your customer's currency at the official National Bank of Poland (NBP) rate. Payment stays in PLN.

== Description ==

Polish stores often sell abroad but keep prices and payments in Polish złoty (PLN). This plugin shows foreign customers how much a product, cart or order costs in their own currency, using the official average exchange rate published by the National Bank of Poland (NBP, tables A and B). **Prices, totals and payments in your store stay in PLN** — the foreign amounts are for information only.

= Features =

* **Daily automatic rate updates** from the NBP Web API — table A on business days (around 12:30 Warsaw time) and table B on Wednesdays, with automatic retries until 16:30.
* **Exact amounts** in the customer's currency (2 decimal places) on product pages, product lists, cart, checkout (classic and block-based), order emails, the thank-you page and *My account*.
* **Totals calculated from line items**, including coupons, shipping, fees and VAT broken down by tax rate.
* **Manual prices** per currency (regular and sale) for simple products, variations and subscriptions — they take precedence over the converted price.
* **Automatic currency** based on the customer's country (Cloudflare `CF-IPCountry` header, WooCommerce geolocation or browser language), with a currency switcher (block, shortcode `[nbpx_currency_switcher]` and widget).
* **"PLN only" countries** (Poland by default): customers from these countries see PLN only. Store administrators can always switch currencies and simulate a customer's country for testing.
* **Cache-friendly**: foreign prices are loaded separately and never cached, so page caching (WP Rocket, LiteSpeed, Cloudflare, WP-Optimize…) does not mix up customers' currencies.
* **Order snapshot**: the currency, rate and NBP table number are saved with every order and shown in emails and in the order screen.
* **Rate anomaly protection**: a large rate change between tables is held for your approval.
* An **"i" icon** next to the foreign price explains the rate, the NBP table and that payment is made in PLN.
* Compatible with **HPOS**, the **block-based cart and checkout**, WooCommerce Subscriptions and email template builders such as YayMail.

= Requirements =

* WooCommerce 9.0 or later with the store currency set to **PLN**. With any other store currency the plugin disables foreign prices and shows a notice.
* PHP 8.2 or later.

= Source code =

All PHP, JavaScript and CSS code is included in the plugin in its original, readable and unminified form — there is no build step. The only generated files are translations: `languages/*.mo` and `languages/*.json` are compiled from the included `languages/*.po` files with WP-CLI (`wp i18n make-mo` and `wp i18n make-json`).

= Disclaimer =

This plugin is not affiliated with, endorsed by or sponsored by Narodowy Bank Polski (National Bank of Poland) or WooCommerce. Exchange rates are taken from the public NBP Web API. Foreign currency amounts are for information only; the store owner is responsible for prices, invoicing and compliance with applicable law.

== External services ==

This plugin connects to the **NBP Web API** (Narodowy Bank Polski — National Bank of Poland) to download the official average exchange rates of foreign currencies. This is required for the plugin to work.

* **What is requested:** the latest exchange rate tables A and B, from `https://api.nbp.pl/api/exchangerates/tables/A/` and `https://api.nbp.pl/api/exchangerates/tables/B/`.
* **When:** right after activation, once a day on business days around 12:30 (Warsaw time) with retries until 16:30, and when an administrator clicks *Fetch rates now*.
* **What is sent:** a standard HTTPS GET request from your server with the user agent `NbpExchangeRate/<version>`. No personal data, no customer data and no store address are sent. As with any web request, NBP receives your server's IP address.
* **Service documentation and terms:** https://api.nbp.pl/en.html (NBP's privacy policy is linked from that page).

No other external services are contacted. Country detection uses the `CF-IPCountry` header that Cloudflare adds to requests (if you enable it), WooCommerce's local geolocation database, or the browser language — the plugin itself does not send visitor data anywhere.

== Installation ==

1. Install and activate the plugin from *Plugins → Add New*, or upload the ZIP file.
2. Make sure the store currency is set to PLN in *WooCommerce → Settings → General*.
3. Go to *WooCommerce → Settings → NBP rates* and choose the currencies and where foreign amounts should be shown.
4. In the *NBP rates* section click *Fetch rates now* (the first fetch also runs automatically after activation).
5. Optional: if your store runs behind Cloudflare, enable *Cloudflare* in *Currency detection* and make sure *Network → IP Geolocation* is on in your Cloudflare zone.
6. Optional: add the currency switcher — the *NBP currency switcher* block, the `[nbpx_currency_switcher]` shortcode or the widget.

== Frequently Asked Questions ==

= Will customers pay in their own currency? =

No. Prices, cart totals and payments stay in PLN. The plugin only shows the equivalent amount in the customer's currency, for information.

= Which currencies are supported? =

All currencies published by the NBP in tables A and B (around 150). You choose which ones are enabled.

= Which exchange rate is used? =

The NBP average exchange rate (kurs średni) from the latest published table. The table number and date are shown next to the price and saved with each order.

= Does it work with page caching and Cloudflare? =

Yes. The page HTML is the same for everyone; foreign prices are loaded separately with caching disabled.

= Can I set my own price in a foreign currency? =

Yes. Each product (and each variation) has *Currency prices* fields. A manual price takes precedence over the converted price.

= Does it work with other multi-currency plugins? =

It is not designed to work together with plugins that change the store currency (e.g. WPML WooCommerce Multilingual currencies, CURCY, Aelia). When the active currency is not PLN, the plugin does not show conversions.

= Where can I get help? =

Use the support forum on WordPress.org.

== Screenshots ==

Screenshots show a Polish store (Polish admin language) with a customer from Germany.

1. Product page: price in PLN with the amount in EUR and the "i" icon explaining the NBP rate and that payment is made in PLN.
2. Block-based cart with amounts in EUR for each item, the coupon, shipping and the VAT breakdown.
3. Order email with amounts in EUR and the currency conversion line with the NBP table number.
4. Settings: enabled currencies, fallback currency and "PLN only" countries.
5. NBP rates: tables A and B, last and next fetch, and the rates of enabled currencies.

== Changelog ==

= 1.0.2 =
* Security: the public price endpoint no longer returns prices of disabled, draft or trashed variations.
* Performance: price ranges of variable and grouped products are cached and the number of products loaded per request is limited.
* Hardening: stricter validation of NBP API data (finite rates, valid dates, table number format); per-order permission check when creating a conversion; approval links for held rates are bound to the currency and decision.

= 1.0.1 =
* Security hardening: the NBP API response size is limited and the request uses wp_safe_remote_get().
* Minimum PHP version raised to 8.2 (PHP 8.1 no longer receives security fixes). Tested with PHP 8.2–8.5.

= 1.0.0 =
* First release.

== Upgrade Notice ==

= 1.0.2 =
Security and performance fixes for the public price endpoint. Recommended for all users.

= 1.0.1 =
Security hardening. Requires PHP 8.2 or later.
