> ## Documentation Index
> Fetch the complete documentation index at: https://developer.surecart.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Currency

> Customize currency formatting, locales, and display

These filters allow you to customize how currency amounts are formatted and displayed throughout SureCart.

## `surecart/currency/format`

Filter the formatted currency string. This is the final output that users see.

<ResponseField name="Parameters" type="Filter Parameters">
  <Expandable title="properties">
    <ResponseField name="$formatted" type="string">
      The formatted currency string (e.g., "\$19.99").
    </ResponseField>

    <ResponseField name="$amount" type="int">
      The amount in cents.
    </ResponseField>

    <ResponseField name="$currency_code" type="string">
      The currency code (e.g., 'USD', 'EUR').
    </ResponseField>
  </Expandable>
</ResponseField>

```php theme={null}
add_filter( 'surecart/currency/format', function( $formatted, $amount, $currency_code ) {
    // Add custom prefix
    return 'Price: ' . $formatted;
}, 10, 3 );
```

## `surecart/currency/locale`

Filter the locale used for currency formatting. This affects number formatting, currency symbol placement, and decimal separators.

```php theme={null}
add_filter( 'surecart/currency/locale', function( $locale ) {
    // Force a specific locale
    return 'en_US';
} );

// Or use WordPress locale
add_filter( 'surecart/currency/locale', function( $locale ) {
    return get_locale();
} );
```

## `surecart/currency/max_cents`

Filter the maximum number of decimal places shown. By default we do not show for whole amounts ().00 cents), but you could modify so it always shows 2 cents.

<ResponseField name="Parameters" type="Filter Parameters">
  <Expandable title="properties">
    <ResponseField name="$decimals" type="int">
      Number of decimal places to display.
    </ResponseField>

    <ResponseField name="$amount" type="int">
      The original amount in cents.
    </ResponseField>

    <ResponseField name="$converted_amount" type="float">
      The converted amount after currency conversion.
    </ResponseField>
  </Expandable>
</ResponseField>

```php theme={null}
add_filter( 'surecart/currency/max_cents', function( $decimals, $amount, $converted ) {
    // Always show 2 decimal places
    return 2;
}, 10, 3 );

// This is our default functionality.
add_filter( 'surecart/currency/max_cents', function( $decimals, $amount, $converted ) {
    // If the amount is a whole number, show no decimals
    return ( $converted == floor( $converted ) ) ? 0 : 2;
}, 10, 3 );
```

## `surecart/currency/filter_url`

To be able to run multi-currency while still maintaining full-page caching, we use a URL parameter to keep track of
the user's chosen currency. To disable URL-based currency switching, you can use this filter.

```php theme={null}
add_filter( 'surecart/currency/filter_url', '__return_false' );

// Or disable only for specific pages
add_filter( 'surecart/currency/filter_url', function( $filter, $permalink ) {
    // Don't add currency params to checkout pages
    if ( strpos( $permalink, 'checkout' ) !== false ) {
        return false;
    }
    return $filter;
}, 10, 2 );
```

## `surecart/display_amount/free`

Filter the text displayed for \$0 prices.

```php theme={null}
add_filter( 'surecart/display_amount/free', function( $text ) {
    return 'No Cost';
} );

// Or with context
add_filter( 'surecart/display_amount/free', function( $text ) {
    return __( 'Complimentary', 'my-theme' );
} );
```

## `surecart/currency_switcher/label`

Filter the currency switcher label text.

```php theme={null}
add_filter( 'surecart/currency_switcher/label', function( $label ) {
    // Lowercase currency code
    return strtolower( $label );
} );

// Or add currency name
add_filter( 'surecart/currency_switcher/label', function( $label ) {
    $currencies = [
        'USD' => 'US Dollar',
        'EUR' => 'Euro',
        'GBP' => 'British Pound',
    ];
    
    return $currencies[ $label ] ?? $label;
} );
```

## Related

<CardGroup cols={2}>
  <Card title="Requests" icon="arrow-right-arrow-left" href="/documentation/actions-filters/requests">
    Modify API requests and responses.
  </Card>

  <Card title="Products" icon="box" href="/documentation/actions-filters/products">
    Customize product display and pricing.
  </Card>
</CardGroup>