View Converted Currency

view_converted_currency converts a numeric amount from one currency code to another using an external API call, then formats the result through CartThrob number formatting.

Current implementation requests conversion from xurrency.com and falls back to the original amount when conversion is unavailable.

See also:

• Global Number Formatting
• view_formatted_number
• developers hooks: cartthrob_view_converted_currency
• utilities tag index

Parameters

See Global Number Formatting.

• price=”10”
• currency_code=”USD”
• new_currency_code=”GBP”
• api_key=”ABCDEF”
• use_prefix=”yes”

price

Amount to convert.

Non-numeric characters are sanitized out, and value is converted to absolute numeric form before API request.

If price is missing, output is empty.

price="10"

currency_code

Source currency code.

Default: number_format_default_currency_code from CartThrob settings.

currency_code="USD"

new_currency_code

Target currency code.

Default: number_format_default_currency_code from CartThrob settings.

If omitted, conversion target equals source default currency.

new_currency_code="GBP"

api_key

Optional API key appended to request URL (?key=...).

api_key="ABCDEF"

use_prefix

When truthy, sets a currency prefix for the target currency (new_currency_code) before formatting output.

Examples: $, £, €, kr, etc.

use_prefix="yes"

Behavior and Constraints

1. This is an immediate-execution single tag.
2. If price is missing, output is empty.
3. price is sanitized and absolute-valued before conversion.
4. Extension hook cartthrob_view_converted_currency runs early; if active, its return value is used directly.
5. If conversion request succeeds (status = ok and value present), output is formatted converted value.
6. If conversion request fails or returns invalid payload, output is formatted original sanitized amount.
7. use_prefix applies prefix based on new_currency_code (not currency_code).
8. Currency codes are normalized to lowercase before request.

Helpful usage note:

If your price value comes from a variable that must be parsed first, ensure your template parse order allows that value to resolve before this tag runs.

Examples

Basic conversion:

{exp:cartthrob:view_converted_currency price="10" currency_code="USD" new_currency_code="GBP"}

With API key:

{exp:cartthrob:view_converted_currency
    price="10"
    currency_code="USD"
    new_currency_code="GBP"
    api_key="YOUR_KEY_HERE"}

Apply target-currency prefix:

{exp:cartthrob:view_converted_currency
    price="$25.99"
    currency_code="USD"
    new_currency_code="EUR"
    use_prefix="yes"}