Tebaro – Currency Conversion for WooCommerce

Description

Tebaro, formerly Tomanify, helps WooCommerce stores convert foreign product costs in USD, EUR, AED, TRY, and CNY into final product prices stored in Iranian Toman or Rial.

Tebaro is a product-pricing/conversion tool. It is not an exchange, broker, market maker, remittance service, financial adviser, or authoritative publisher of currency buy/sell quotations.

The core pricing model remains deliberately simple and upgrade-safe:

• Final conversion values are stored canonically as integer Toman values.
• Foreign products keep an integer Toman baseline in product meta.
• Product pricing uses: Foreign price × conversion value × (1 + margin/100), rounded to the nearest 1000 Toman.
• Toman display writes the baseline directly; Rial display writes baseline × 10.
• Switching Toman/Rial rewrites WooCommerce prices from the saved baseline and does not re-fetch sources or recalculate from the foreign amount.

Conversion source modes

Tebaro provides four administrator-facing modes:

• Automatic fallback — tries Official-rate estimate, then Offline estimate, then Manual conversion values.
• Official-rate estimate — reads administrator-configured HTTPS official Rial observations and applies an effective estimate calibration coefficient.
• Offline estimate — uses locally stored official reference data, CAGR, an official cross-currency snapshot when available, and a cached/manual coefficient. Offline mode performs no external request.
• Manual conversion values — uses administrator-entered per-currency Toman values and performs no external request.

No source URL is bundled, pre-filled, hidden, or used as a fallback. External requests are possible only after an administrator explicitly configures HTTPS URLs.

Estimate calibration coefficient

The manual fallback coefficient is stored locally and remains administrator-controlled.

Administrators may optionally enable a separate HTTPS coefficient feed. The feed supplies one dimensionless scalar coefficient, not per-currency market rates or provider lists. The plugin never uses the feed to overwrite the manual fallback coefficient.

The accepted feed schema is intentionally narrow:

{
  "schema_version": 1,
  "coefficient": 1.294,
  "generated_at": "2026-10-06T12:00:00Z",
  "valid_until": "2026-10-07T12:00:00Z",
  "method": "median_of_currency_medians_v1",
  "sample_count": 25,
  "status": "ok"
}

Unknown top-level keys are rejected. Payloads containing per-currency values, provider lists, provider/source URLs, or similar rate-feed fields are not accepted by this schema.

The plugin also applies local freshness/TTL checks, a bounded last-known-good cache, a seven-day cache grace window, and a scalar jump guard before using a newly received coefficient.

Legacy JSON migration

The former multi-provider/free-market JSON runtime is retired in revised 1.1.0.

On upgrade, Tebaro protects existing shops instead of silently switching a legacy JSON-dependent installation to a different source:

• when current stored values can be preserved safely and no existing Manual values conflict, stored values may be copied to Manual conversion values without changing current canonical rates or product prices;
• when existing Manual values could be overwritten, stored values are unavailable, or migration is ambiguous, the plugin enters a Legacy migration hold;
• while Hold is active, source refreshes and refresh-driven full product recalculation are paused until an administrator explicitly resolves the migration;
• the old JSON URL may remain locally for one transition release as inactive legacy data, but it is never requested by the revised runtime and is not included in new backups.

Independence and naming

Tebaro, formerly Tomanify, is an independent free and open-source WordPress/WooCommerce project. It is not affiliated with, endorsed by, operated by, or connected with tomanify.com or any exchange, brokerage, cryptocurrency platform, or remittance service.

The public display name changed to Tebaro while the technical WordPress identity remains tomanify for safe in-place updates. Existing option names, hooks, classes, the plugin folder/slug, text domain, and shortcode remain technically compatible.

Key Features

• Foreign-product pricing: foreign flag, currency, foreign amount, and margin (%)
• Canonical integer-Toman conversion values
• Per-product Toman baseline for safe Toman/Rial switching
• Automatic fallback: Official → Offline → Manual
• Administrator-configured HTTPS official source URLs; empty by default
• Manual fallback coefficient plus optional scalar-only automatic coefficient feed; disabled/empty by default
• Deterministic no-network Offline mode
• Manual conversion values in Toman
• Stored local source/provenance labels without frontend network requests
• Bulk editor for foreign products
• Frontend shortcode: [tomanify_rates]
• Frontend assets load only when the shortcode is rendered
• Optional same-host cache purge, disabled by default
• Backup/Restore with legacy-migration safeguards
• Independent plugin locale: site, en_US, or fa_IR
• Explicit RTL/LTR containers based on the plugin locale
• Guided onboarding and product-editor steps

Supported Currencies

USD, EUR, AED, TRY, CNY

Usage

Official-rate estimate

For each supported currency, the administrator may enter an HTTPS URL that returns the official Rial observation in the supported text/RSS/XML form.

For a valid observation, Tebaro calculates:

Estimated Toman conversion value = Official Rial observation × Effective coefficient ÷ 10

If all five official observations are valid in the same refresh, the plugin records a coefficient-independent official cross-currency ratio snapshot for future Offline estimates.

The plugin does not bundle or recommend a specific official endpoint. Empty URL fields disable Official-rate retrieval for that currency.

Offline estimate

Offline mode makes no external request. It uses the last real stored official USD observation, its timestamp, the administrator CAGR setting, the latest complete official ratio snapshot when available, and a locally usable cached/manual coefficient.

Until a valid official ratio snapshot exists, the existing deterministic compatibility fallback remains available.

Manual conversion values

Manual mode uses the administrator-entered Toman values directly. It does not contact an external service.

Foreign products

Open a WooCommerce product and use the Foreign Product (Tebaro) box:

• Enable Is foreign product
• Enter Foreign price
• Choose Currency
• Enter Margin (%)

Only products with the foreign flag enabled are eligible for conversion updates.

Shortcode

Use:

[tomanify_rates]

The widget can show the selected conversion values, display unit, optional last-update time, and locally recorded source/provenance. It does not fetch rates or coefficients from the frontend.

The public note explains that the values are estimates for product pricing and are not currency buy/sell quotations.

Backup and Upgrade Safety

New backups contain portable user configuration and selected foreign-product meta. Derived runtime state is not treated as authoritative portable configuration.

New exports do not include the retired legacy JSON URL or retired provider/anomaly settings. Old backups that contain the legacy JSON source are recognized only through the compatibility path and cannot silently reactivate the old runtime.

A backup made while Legacy Hold is active restores into Hold. Import does not queue a full product recalculation while Hold remains unresolved.

Normal plugin updates do not intentionally overwrite administrator-entered official URLs, Manual values, a custom coefficient, locale, display unit, cron interval, CAGR, shortcode selections, purge preference, foreign-product meta, or existing product baselines except for specifically documented compatibility migrations.

Documentation

• Main documentation: https://tomanify.github.io/docs/
• Quick Start: https://tomanify.github.io/docs/quick-start/
• Sources & Coefficient: https://tomanify.github.io/docs/sources/
• Public coefficient-index repository (optional): https://github.com/tebaro-wp/coefficient-index

These links are documentation/reference links only. Source and coefficient URL fields remain empty by default and are filled only by an administrator.

External Services

Tebaro has no bundled, required, hidden, or default external rate/coefficient endpoint. All external-source URL fields are empty by default. Documentation may link to the optional public Tebaro Coefficient Index, but the plugin never copies that feed URL into settings automatically.

External requests can occur only after an administrator explicitly configures HTTPS URLs and the corresponding runtime mode uses them. There are two possible external request families:

1. Official-rate source URLs — one administrator-selected URL per supported currency. During an explicit or scheduled Official/Automatic refresh, Tebaro may request those URLs and parse supported official Rial observations.
2. Optional calibration-coefficient feed URL — disabled by default and empty by default. When explicitly enabled, Tebaro may request this URL during an Official/Automatic refresh after at least one valid official observation exists. The expected response contains one scalar coefficient plus bounded metadata; it is not a per-currency market-rate feed.

Offline mode and Manual mode make no external request. The frontend shortcode makes no external rate/coefficient request.

Plugin code does not send customer data, order data, product data, personally identifiable store-user data, analytics, or telemetry to configured source URLs. Like any HTTPS request, the destination server can observe ordinary connection/HTTP metadata such as the requesting server IP address. Requests also use the plugin’s compatibility User-Agent identifier Tomanify/<version>; coefficient requests additionally declare JSON acceptance.

Tebaro does not bundle a required external service. Administrators choose whether to configure any documented optional endpoint, including the public Tebaro Coefficient Index. Before configuring any endpoint, the site administrator is responsible for reviewing the chosen service or repository policies, permissions, privacy implications, and applicable law. Configuring a URL is an explicit administrator action.

The legacy multi-provider JSON URL from older versions is inactive migration data only: revised runtime code does not request it, normal UI does not expose it as a source, and new backups do not export it.

Privacy

Tebaro does not include tracking, advertising telemetry, remote JavaScript/CSS/fonts, tracking pixels, or remote frontend assets.

The plugin stores operational configuration in WordPress options and foreign-product configuration in product meta. It does not transmit customer/order/product content to external source URLs.

Administrators should consider the privacy and terms of any third-party endpoint they choose to configure, including the ordinary server/network metadata visible to that endpoint during an HTTPS request.

License

GPL-2.0-or-later.