Multi-currency

Supported currencies

moneda accepts the ISO code ("CRC", "USD") or the internal code ("01", "02"). Each tenant defines which currencies it has active: the catalog is read from its own configuration, not from a fixed list.

Which currency is used if moneda isn’t sent

The tenant’s primary currency, which isn’t always the colón. A tenant that operates in dollars issues in dollars when the field is omitted.

A tenant can be limited to a single currency

If the tenant is not enabled for multi-currency, the document is issued in its primary currency even if the request asks for another one. This is a server-side guarantee, not a request error: it doesn’t return 400, it issues in the tenant’s currency.

That’s why the response always returns the currency the document was actually issued in, not an echo of what was sent. If you requested CRC and the response says USD, the tenant is limited to dollars and needs to be enabled for multi-currency.

Exchange rate

The exchange rate is the one configured on the tenant, which an administrator maintains from the POS.

{ "moneda": "USD", "tipoCambio": 670.50 }

If tipoCambio is sent, the sent value is respected — useful when the integrator’s system manages a fixed exchange rate by policy.

{ "moneda": "USD" }

If it isn’t sent, the tenant’s rate is used. If the tenant has none defined, issuance is rejected: no value is invented and no external source is queried, because a wrong exchange rate ends up written into a fiscal document.

{
  "error": "No hay un tipo de cambio definido. Un administrador debe establecerlo desde la barra superior antes de facturar en otra moneda."
}

Catalog prices and conversion

Catalog prices are written in a single currency per tenant, which isn’t necessarily the document’s currency.

When a line doesn’t send precioUnitario, the list price is taken and converted to the document’s currency using the tenant’s exchange rate. A $4,88 product invoiced in colones with an exchange rate of 500 comes out to ₡2.440.

When the line does send precioUnitario, it’s respected as-is: it’s assumed to already be expressed in the currency the request asked for, and it isn’t converted.

Sending an explicit precioUnitario is the most predictable way to integrate, especially if the integrator’s system already manages its own prices.

Credit and debit notes: currency is inherited

A credit note (NC) or debit note (ND) inherits the currency and exchange rate of the document it corrects, even if the request sends different ones or omits them.

Hacienda requires them to match the referenced document and rejects the document if they don’t: error -510 for the currency and -511 for the exchange rate. Since the rejection arrives asynchronously, inheriting is the only combination that avoids discovering it hours later.

If the referenced document wasn’t issued by this system and isn’t found, whatever the request sends is respected.

Why it matters

• Hacienda requires the XML totals to be expressed in the document’s original currency.
• The exchange rate is recorded on the document: it’s the one used for reports in colones.

See also: currency catalog · totals calculation.