Socotra multicurrency mode allows each tenant to support an unlimited number of currencies, and each policy in the system may use a different currency.

In Socotra, currency is used for the following operations:

  • Determining the level of precision (the number of decimal places) each financial value has when persisted to the database

  • Rendering the value and currency symbol in the user interface

  • Indicating the governing currency in API responses

Enabling Multicurrency

Newly created tenants will have multicurrency enabled by default. However, by default, the user interface will not display multiple currencies, and you may continue to use a single currency with multicurrency enabled.

When you are ready to enable multiple currencies in the UI, set the UI feature flag property.ui.multicurrency.enabled to true.

To enable multicurrency for an older tenant, add the flag to config.json in the configuration package; for example:


Single-currency mode is deprecated and will be removed in a future release. Socotra recommends turning on multicurrency mode for all tenants. See the section below on legacy considerations before enabling multicurrency for existing production tenants.

The multicurrency feature flag is called property.multicurrency.enabled. To turn multicurrency on for an older tenant, add the flag to config.json in the configuration package; for example:

  "timezone": "America/Los_Angeles",
  "currency": "EUR",
  "features": {
    "property.multicurrency.enabled": true

In this case, config.json tells Socotra that the default currency for the tenant will be euros, but will enable each policy to have a currency that may be different than the default.


Once the feature flag is turned on for a tenant, it cannot be turned off. Use care before enabling the feature flag in production tenants.


When multicurrency in enabled, the meaning of the currency property in config.json changes from “the currency that each policy has” to “the currency that each new policy will have unless it is overridden at the time the policy is created.” The override is done by specifying a different currency with the currency property in the PolicyCreateRequest when creating a new policy. The currency property is optional, and if not specified, the policy will use the tenant default currency.

After the policy is created, the currency for that policy is bound and cannot change.


Currencies are indicated in the API with this currency property on the PolicyCreateRequest and PolicyResponse objects.

The invoice object also has the currency property to disambiguate currencies when invoices for a policyholder are fetched, since those invoices may be based on policies that have different currencies.

Document Rendering and Plugins

In plugins and document templates the data.policy object includes a currency property.

User Interface

Multiple currencies are disabled be default in the user interface. When you are ready to include multiple currencies in the UI, set property.multicurrency.enabled to true.

The Socotra user interface will adapt for each policy to use the currency set for the policy. This will include how financial amounts are displayed and the currency symbol used. For currencies that don’t have a supported symbol, the three-letter currency code will be used, for example, BHD.


If policies that have different currencies are included in a report, then each record may have financial values that are based in different currencies. If these amounts need to be disambiguated, that will have to be done after the report is generated. (Socotra is creating a new reporting infrastructure that will have a simpler mechanism for reports that span currencies, expected later this year.)

Legacy Considerations


If multicurrency is not enabled, the system will operate in a single-currency mode. This mode is different from the default multicurrency mode in these aspects:

  • The currency property will not appear on the PolicyCreateRequest object or the PolicyResponse object.

  • Several objects will have a currency property appear. Note that the value of the property is redundant with the currency set for the tenant in config.json. See below for the specific objects that are affected.

Currency Properties in the API

Turning on multicurrency streamlines the existing API objects which have currency properties. For example, the PerilCharacteristicsResponse had five currency properties, such as indemnityPerEventCurrency. Since these never vary within a single policy, they are redundant and are removed when multicurrency is turned on.

If multicurrency is off, the following objects will contain redundant currency properties:


If your integration code will fail if Socotra responses are missing currency properties, that code should be updated before enabling your production tenants for multicurrency.