Tipo de Cambio Costa Rica: USD to CRC Rates in WordPress

Tipo de Cambio Costa Rica is a free WordPress plugin I wrote. It shows the US dollar exchange rate in Costa Rican colones, buy and sell, and converts prices between the two currencies. It needs no API key and has no settings.

I released version 1.0 in 2017. It stopped working when its data source disappeared, so 2.0.0 is a rewrite. This post covers how to use it, then what broke and how the new version is built. There is a short version in Spanish at the end.

Install the plugin

1. In WordPress, open Plugins > Add New Plugin and search for Tipo de Cambio Costa Rica.
2. Install and activate it.
3. Edit a post or page and add a Shortcode block with [WPTCR_TIPO_CAMBIO_VENTA].

The page now shows the current sell rate. The plugin requires WordPress 6.0 and PHP 7.4 or later.

Shortcodes

The examples use a buy rate of 448.98 and a sell rate of 454.07.

Shortcodes print only the number, so you add the currency symbol and any text around them: Venta: ₡[WPTCR_TIPO_CAMBIO_VENTA].

monto defaults to 100. It accepts 20000, 20000.50, 20,000 and ₡20,000. An invalid amount prints nothing.

Use it in a theme

The same values are available as PHP functions:

echo esc_html( wptcr_tipo_cambio( 'VENTA' ) );              // 454.07
echo esc_html( wptcr_convertir_colones_dolares( 25000 ) );  // 55.06
echo esc_html( wptcr_convertir_dolares_colones( 100 ) );    // 44898.00

All three return 0 when no rate is available.

Where the rate comes from

The rate is the reference rate of the Central Bank of Costa Rica (BCCR), as published by the public API of the Ministerio de Hacienda:

curl https://api.hacienda.go.cr/indicadores/tc/dolar

{
  "venta": { "fecha": "2026-11-05", "valor": 454.41 },
  "compra": { "fecha": "2026-11-05", "valor": 449.63 }
}

I compared these values with BCCR's own indicators 317 and 318 before switching, and they matched. The plugin refreshes the rate every 4 hours with a WP-Cron event.

What broke in 1.0

Version 1.0 called a SOAP web service at indicadoreseconomicos.bccr.fi.cr. That host no longer resolves. Running the old code against it on PHP 8.3 gives this:

Fatal error: Uncaught TypeError: number_format(): Argument #1 ($num) must be of type int|float, string given

The failed request left an empty string, and number_format() does not accept one on PHP 8. A page showing the rate went down whenever a refresh came due. On PHP 7.4 the same call raises a warning and returns null, and 1.0 saved that as an empty rate, so the page printed 0.

The refresh also ran inside the page request, with no timeout on the cURL call, so a slow service meant a slow page.

Reading the old code turned up more:

• The age check read the wrong field. $diff->h from date_diff() is only the hours part of the interval. A rate 1 day and 2 hours old has h = 2, so it passed as fresh.
• Conversions used the wrong rate. They passed the constant 318 to a function that compared $tipo === "VENTA". Nothing matched, so colones to dollars used the buy rate instead of the documented sell rate. With the rates above, ₡20,000 gave $44.55 instead of $44.05.
• It changed the timezone for everyone. date_default_timezone_set() ran on every call, which affected date calculations in WordPress and other plugins.
• A non-numeric amount was fatal on PHP 8. monto="abc" reached a division and threw a TypeError.

How 2.0 is built

Version 2.0.0 is repair work, with no new features.

Pages read, cron writes

A WP-Cron event fetches the rate and stores it in two options. Pages only read those options, so the API has no effect on page load. A failed fetch returns before it touches anything, which keeps the last valid rate in place during an outage:

function wptcr_actualizar_tipo_cambio() {
  $tasas = wptcr_consultar_hacienda();
  if ( is_wp_error( $tasas ) ) {
    return false;
  }

  $momento = wptcr_ahora_cr()->format( 'Y-m-d H:i:s' );

  update_option( 'WPTCR_COMPRA_CR', number_format( $tasas['compra'], 2, '.', '' ) . '|' . $momento );
  update_option( 'WPTCR_VENTA_CR', number_format( $tasas['venta'], 2, '.', '' ) . '|' . $momento );
  delete_transient( 'wptcr_reintento' );

  return true;
}

The first request is the exception

Right after installation nothing is stored, so a page that needs the rate queries the API once, with a 5-second timeout. A lock keeps simultaneous requests from doing the same, and after a failure there is no new attempt for 15 minutes:

function wptcr_actualizar_ahora() {
  if ( false !== get_transient( 'wptcr_reintento' ) || false !== get_transient( 'wptcr_bloqueo' ) ) {
    return false;
  }

  set_transient( 'wptcr_bloqueo', 1, 30 );
  $actualizado = wptcr_actualizar_tipo_cambio();
  delete_transient( 'wptcr_bloqueo' );

  if ( ! $actualizado ) {
    set_transient( 'wptcr_reintento', 1, 15 * MINUTE_IN_SECONDS );
  }

  return $actualizado;
}

Transients are not atomic, so two requests can still get past the lock. Here that costs one extra API call.

API responses get validated

Both rates must be positive numbers with a valid date that is not later than today in Costa Rica. Anything else counts as a failed fetch, and the stored rate stays. Dates use DateTimeImmutable with an explicit America/Costa_Rica timezone, so the global timezone stays untouched.

No rate means no output

Without a rate, shortcodes print nothing and the PHP functions return 0. Printing 0 on a store page would read as a real price.

Existing sites keep working

Sites on 1.0 depend on its function names, uppercase shortcodes, constants and the valor|Y-m-d H:i:s format of its options, so all of those stayed. The $fecha argument is deprecated and ignored.

WordPress does not run activation hooks on updates, so the plugin compares a stored version on init and runs its migration when the version changes. The migration schedules the cron event and removes invalid rates saved by 1.0:

function wptcr_verificar_version() {
  if ( WPTCR_VERSION !== get_option( 'wptcr_version' ) ) {
    wptcr_migrar();
  }
}
add_action( 'init', 'wptcr_verificar_version' );

Get the plugin

Tipo de Cambio Costa Rica is on WordPress.org, free and licensed under the GPL. If you still run 1.0, update it, because 1.0 no longer works. Questions and bug reports go in the support forum.

En español

Tipo de Cambio Costa Rica es un plugin gratuito de WordPress que muestra el tipo de cambio del dólar en colones, compra y venta, y convierte montos entre colones y dólares. No necesita API key, token ni configuración.

Los datos son el tipo de cambio de referencia del Banco Central de Costa Rica (BCCR), publicado por la API del Ministerio de Hacienda. Se actualizan solos cada 4 horas, y si la API no responde, el sitio sigue mostrando el último valor válido.

Para empezar, instale el plugin desde el menú Plugins de WordPress y agregue 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"].

Si todavía usa la versión 1.0, actualice el plugin, porque esa versión dejó de funcionar cuando el BCCR retiró el servicio que usaba.