Session and reference currency

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Session and reference currency

    ServiceNow AI Platform® manages currency fields using two types of currencies: session currency and reference currency. This dual-currency approach supports multi-currency environments by storing currency values both as entered by the user and converted into a system-wide standard currency for calculations.

    Show full answer Show less

    Session currency

    The session currency is determined by the user's locale or single-currency mode settings. It reflects the currency format and symbol familiar to the user, displaying values in a localized number format that varies by region (e.g., decimal and thousand separators). Users see currency values either as originally entered or converted into this session currency.

    The session currency is identified through:

    • Single-currency mode configuration via system properties
    • Default currency associated with the user's locale

    Reference currency

    The reference currency is the system-wide standard currency used for consistent calculations across the instance. Currency values entered by users are stored in three forms: the original value and currency code as per the user's locale, and the value converted to the reference currency using current exchange rates.

    The reference currency is determined by:

    • System locale configured by the glide.system.locale property
    • Fallback to Java default locale (typically en.US)

    Practical implications and common issues

    Filtering, sorting, and aggregation of currency fields rely on the reference currency values, while users see session currency values. Because exchange rates fluctuate, this can cause discrepancies where filtered lists or aggregated totals do not appear in the expected order or amounts from the user’s perspective.

    Additional confusion arises because currency formatting depends on the user's locale rather than the currency code itself, potentially causing inconsistencies in how currency values are displayed.

    What this means for ServiceNow customers

    • Expect currency fields to maintain both the original user-entered value and a system-wide converted value for calculations.
    • Be aware that filtering and aggregation on currency fields use reference currency values, which may differ from displayed session currency values due to exchange rate changes.
    • Understand that localized formatting affects currency display and may vary between users with different locales.
    • Plan for potential discrepancies when sorting or aggregating currency data and communicate these nuances to end users to manage expectations.

    The default, or standard, currency fields in the ServiceNow AI Platform® use two kinds of currency, Session and Reference.

    Session currency
    The session currency is defined for the user by the user’s locale or single-currency mode.
    Reference
    The system local determines the reference currency, and is the standard used across the entire instance.
    Each time you enter a value into a currency or price field, the system stores three pieces of information:
    • Value as entered, in the user's locale.
    • Currency code, in the user's locale.
    • Value converted to the reference currency using the current exchange rate.
    Note:
    In multiple-currency mode, the currency code saved in the currency field may not be the same as the session currency code. For example, the session currency could be the Euro and the number entered could be the Japanese Yen.

    Session currency

    When users view a currency value, they can see the value as entered or in the session-currency format. The format contains the:
    • Currency symbol
    • Value converted to the session currency and shown in a localized number format.

    The user’s locale determines the session currency format.

    The number format can differ in features such as the decimal separator based on the locale. For example, the US formatting is 1,234,567.89, while German formatting is 1.234.567,89. The ServiceNow AI Platform® determines the session currency in the following sequence:
    • Single-currency mode setup using glide.i18n.single_currency and glide.i18n.single_currency.code.
    • Default currency for the user’s locale.

    Reference currency

    To perform calculations on heterogeneous currency values, the ServiceNow AI Platform® stores currency values converted to a system currency, referred to as the reference currency. Every currency field contains a reference currency value. The system determines the reference currency in the following sequence:
    • System locale set using the property glide.system.locale
    • Java default locale, typically en.US

    The filtering and aggregation features use the reference currency value to perform calculations on default currency fields. These features can yield inaccurate results because of conversion rate changes.

    Issues with currency fields

    Users are often confused by the results of filtering, sorting, and displaying currency fields because the system works with at least two currencies for each value: the session currency and the reference currency.

    Note:
    Aggregations and filtering of currency fields use the reference currency, and the user sees the session currency. Because of changing conversion rates, the filtered reference currency values might not result in the same order as the session currency values would suggest. The same issue happens with aggregations.
    The user might see the following issues:
    • Lists filtered on currency fields might not be in the expected order. It uses the reference currency values for filtering but displays session currency values.
    • Aggregation of currency fields may not produce the expected results because reference currency values are aggregated, and then converted to the session currency.
    • Currency values may not appear as expected because currency values are formatted based on the user's locale and not on the currency code.

    This confusion may be the result of the difference between session and reference currencies, changing conversion rates, and different session currencies used by different users.