Description
Show your visitors today’s US dollar exchange rate in Costa Rican colones and convert prices between colones and dollars, with no API key, token or settings. Add a shortcode and the rate keeps itself up to date.
The rates are the reference exchange rate of the Central Bank of Costa Rica (BCCR), as published by the public API of Costa Rica’s Ministry of Finance (Ministerio de Hacienda). See “External services” below.
Features
- Buy (compra) and sell (venta) rates of the US dollar in any post, page, widget or template.
- Conversions from colones to dollars and from dollars to colones.
- Automatic updates every 4 hours in the background (WP-Cron).
- If the API is not available, your site keeps showing the last valid rate.
- No settings, no API key and no token.
- Works with the block editor (Shortcode block), the classic editor and theme templates.
- Lightweight: it adds no scripts or styles to your pages.
Quick start
- Install and activate the plugin from Plugins > Add New Plugin.
- Edit a post or page and add a Shortcode block with
[WPTCR_TIPO_CAMBIO_VENTA]. - Publish it. The page shows the current sell rate, for example
454.07.
Shortcode reference
The example outputs use a buy rate of 448.98 and a sell rate of 454.07.
Buy rate (compra)
[WPTCR_TIPO_CAMBIO_COMPRA]
Output: 448.98
Sell rate (venta)
[WPTCR_TIPO_CAMBIO_VENTA]
Output: 454.07
Colones to dollars (uses the sell rate)
[WPTCR_CONVERTIR_COLONES_DOLARES monto="20000"]
Output: 44.05
Dollars to colones (uses the buy rate)
[WPTCR_CONVERTIR_DOLARES_COLONES monto="10"]
Output: 4489.80
If monto is omitted, 100 is used. The shortcodes print only the number, so you can add the currency symbol and any text around them, for example Venta: ₡[WPTCR_TIPO_CAMBIO_VENTA]. If the rate is not available or monto is not a valid amount, they print nothing.
PHP function reference
Use these functions in your theme templates, and escape their output when you print it. The example outputs use the same rates as above.
wptcr_tipo_cambio( $tipo ) returns the rate as a number. $tipo is 'COMPRA' (the default) or 'VENTA', in any case.
<?php echo esc_html( wptcr_tipo_cambio( 'VENTA' ) ); ?>
Output: 454.07
wptcr_convertir_colones_dolares( $monto ) returns the amount in dollars, as a string with two decimals.
<?php echo esc_html( wptcr_convertir_colones_dolares( 25000 ) ); ?>
Output: 55.06
wptcr_convertir_dolares_colones( $monto ) returns the amount in colones, as a string with two decimals.
<?php echo esc_html( wptcr_convertir_dolares_colones( 100 ) ); ?>
Output: 44898.00
All of them return 0 if the rate is not available.
En español
Muestra en su sitio el tipo de cambio de referencia del dólar (compra y venta) y convierte montos entre colones y dólares, sin configuración ni token. Los datos vienen de la API pública del Ministerio de Hacienda y se actualizan solos cada 4 horas. Si la API no responde, el sitio sigue mostrando el último valor válido.
Para empezar basta con agregar un bloque Shortcode con [WPTCR_TIPO_CAMBIO_COMPRA] o [WPTCR_TIPO_CAMBIO_VENTA]. Para convertir montos están [WPTCR_CONVERTIR_COLONES_DOLARES monto="20000"] y [WPTCR_CONVERTIR_DOLARES_COLONES monto="100"].
External services
This plugin connects to the public API of the Ministerio de Hacienda (Ministry of Finance) of Costa Rica to get the reference exchange rate of the US dollar (buy and sell rates). The plugin needs this service to show the exchange rate.
- Service: API of the Ministerio de Hacienda, endpoint
https://api.hacienda.go.cr/indicadores/tc/dolar. - When: every 4 hours from WP-Cron, and once when a page needs the rate and no rate has been stored yet (for example, right after installing the plugin).
- Data sent: a plain HTTP GET request with no parameters. It does not include personal data, cookies or any content or URL of your site. The request identifies itself with the User-Agent
TipoDeCambioCR/<plugin version> (+https://wordpress.org/plugins/tipo-de-cambio-costa-rica/). As with any HTTP request, the API receives the IP address of your server. - Usage policies and limits of the API: https://api.hacienda.go.cr/docs/
- Privacy policy of the Ministerio de Hacienda (Directriz DM-009-2021): https://www.hacienda.go.cr/docs/PoliticadePrivacidadDirectrizN.DM-009-2021.pdf
Installation
- Install the plugin from the Plugins screen in WordPress, or upload the plugin files to the
/wp-content/plugins/tipo-de-cambio-costa-ricadirectory. - Activate the plugin through the Plugins screen in WordPress.
- Add the shortcodes to a post or page, or call the PHP functions from your theme.
FAQ
Where does the exchange rate come from?
From the public API of the Ministerio de Hacienda of Costa Rica, which publishes the reference exchange rate of the Central Bank of Costa Rica (BCCR). Version 1.0 used a BCCR web service that has been discontinued.
How often is the rate updated?
Every 4 hours, with a WP-Cron event that is scheduled when the plugin is activated or updated. If your site defines DISABLE_WP_CRON, make sure a server cron job runs wp-cron.php; otherwise the rate will not be refreshed.
What happens if the API is not available?
The plugin keeps showing the last rate obtained successfully. If no rate has been obtained yet (for example, right after installing the plugin), it queries the API once when a page needs the rate, waiting at most 5 seconds. If that fails, it does not try again during the next 15 minutes. While there is no rate, the shortcodes print nothing and the PHP functions return 0.
Which formats does “monto” accept?
Numbers with a point as decimal separator (20000, 20000.50). Commas are accepted as thousands separators (20,000, 1,500,000.50), and spaces and the ₡ and $ symbols are ignored (₡20,000). Any other value is not converted.
Which rate is used for the conversions?
Colones to dollars uses the sell rate (venta). Dollars to colones uses the buy rate (compra).
Screenshots




Changelog
2.0.0
- New data source: the public API of the Ministerio de Hacienda. The BCCR web service used by version 1.0 was discontinued, so 1.0 no longer works.
- The rate is updated every 4 hours by a WP-Cron event. Pages only read the last valid rate and never wait for the API, except once when no rate has been stored yet.
- If the API fails, the last valid rate is kept. Without any rate, the shortcodes print nothing and the functions return 0.
- Changed: colones to dollars conversions now use the sell rate (venta), as documented. Version 1.0 used the buy rate (compra) by mistake, so the results are now slightly lower.
- Fixed: fatal errors on PHP 8 when the data source was not available or when
montowas not a number. - Fixed: the plugin no longer changes the default PHP timezone, which affected the date calculations of WordPress and other plugins.
- Fixed: the stored rate was not refreshed when it was more than one day old.
- Fixed:
wptcr_tipo_cambio()now accepts the type in any case ('venta') and theWPTCR_COMPRA_CRandWPTCR_VENTA_CRconstants. - Fixed:
montoaccepts thousands separators and currency symbols (₡20,000). Invalid values are no longer converted. - Fixed: the buy and sell labels were swapped in this readme.
- Deprecated: the
$fechaargument ofwptcr_tipo_cambio(). It is ignored and the current rate is always returned. - Deprecated:
wptcr_get_bccr_service_data(). - Security: escaped output, sanitized shortcode attributes, and the WordPress HTTP API instead of cURL.
- Requires WordPress 6.0 and PHP 7.4.
1.0
- Initial release.
