Umbraco Commerce
CMSCloudHeartcoreDXP
13.latest (LTS)
13.latest (LTS)
  • Umbraco Commerce Documentation
  • Release Notes
    • v13.1.0-RC
  • Commerce Products
    • Commerce Packages
    • Commerce Payment Providers
    • Commerce Shipping Providers
  • Installation
    • Installing Umbraco Commerce
    • Licensing
  • Upgrading
    • Upgrading Umbraco Commerce
    • Version Specific Upgrade Notes
    • Migrate from Vendr to Umbraco Commerce
      • Migrate Umbraco Commerce Checkout
      • Migrate custom Payment Providers
  • Getting Started
    • Introduction
    • Umbraco Configuration
    • User Interface
  • How-To Guides
    • Overview
    • Configure SQLite support
    • Limit Order Line Quantity
    • Use an Alternative Database for Umbraco Commerce Tables
    • Add item to Cart
    • Update Cart
    • Delete item in Cart
    • Customizing Templates
  • Key Concepts
    • Get to know the main features
    • Base Currency
    • Bulk Actions
    • Calculators
    • Dependency Injection
    • Discount Rules / Rewards
    • Events
      • List of validation events
      • List of notification events
    • Fluent API
    • Order Calculation State
    • Payment Forms
    • Payment Providers
    • Pipelines
    • Price/Amount Adjustments
    • Price Freezing
    • Product Adapters
    • Product Bundles
    • Product Variants
      • Complex Variants
    • Properties
    • ReadOnly and Writable Entities
    • Search Specifications
    • Settings Objects
    • Shipping Package Factories
    • Shipping Providers
    • Shipping Range/Rate Providers
    • Tax Sources
    • UI Config Files
    • Umbraco Properties
    • Unit of Work
    • Umbraco Commerce Builder
    • Webhooks
  • Tutorials
    • Overview
  • Reference
    • Stores
    • Shipping
      • Fixed Rate Shipping
      • Dynamic Rate Shipping
      • Realtime Rate Shipping
    • Storefront API
      • Endpoints
        • Order
        • Checkout
        • Product
        • Customer
        • Store
        • Currency
        • Country
        • Payment method
        • Shipping method
        • Content
    • Go behind the scenes
Powered by GitBook
On this page
  • Currency Exchange Rates
  • Historic Orders

Was this helpful?

Edit on GitHub
Export as PDF
  1. Key Concepts

Base Currency

Base Currency for standardized reporting in Umbraco Commerce.

PreviousGet to know the main featuresNextBulk Actions

Last updated 1 year ago

Was this helpful?

Within Umbraco Commerce we have support for showing analytics reports, including summaries of sales figures. At the same time, Umbraco Commerce also supports orders being placed in multiple currencies. These pose a problem of how to display a succinct sales figure when the orders are placed in multiple currencies. The answer to this is the store's Base Currency.

When you configure a store you need to assign a base currency to it. This currency is there to identify which currency the store should use as its basis for reports and sales figures. This will be used regardless of whatever currency the order was placed in.

When a store has a base currency configured, any order placed will track the price of the order in the customer's chosen currency. It will also track the current exchange rate between that currency and the store's base currency. Whenever a report is run the order total prices will be converted using this exchange rate. This means that they can all be automatically presented in the single base currency of the store.

Currency Exchange Rates

Umbraco Commerce uses an ICurrencyExchangeRateService to retrieve the most up-to-date rate to be able to track the current exchange rate. This is done for each individual order.

Out of the box, Umbraco Commerce comes with a number of available services you can choose to use. Some are free services, whilst others require a paid subscription.

  • ExchangeRatesApiCurrencyExchangeRateService uses the free API and is the default option.

  • FixerCurrencyExchangeRateService uses the API which is a reliable paid option (with a reasonable free plan).

  • CurrencyLayerCurrencyExchangeRateService uses the API which is another reliable paid option (with a reasonable free plan).

If you wish to change the currency exchange rate service used, you can do so via the approach. This is used to override the default service configuration. For services that require configuration to be passed in, such as service API keys, you'll need to use the factory-based override as follows:

public static class UmbracoCommerceUmbracoBuilderExtensions
{
    public static IUmbracoCommerceBuilder AddMyServices(IUmbracoCommerceBuilder builder)
    {
        // Register the fixer tax service with your API key
        builder.Services.AddUnique<ICurrencyExchangeRateService>(new FixerCurrencyExchangeRateService("YOUR_FIXER_API_KEY"));
        
        // Return the builder to continue the chain
        return builder;
    }
}

Historic Orders

Umbraco Commerce has a background service that will attempt to ensure that all historic orders without an exchange rate defined get updated. This is done in case the third-party APIs fail and we need a method of cleaning data. It is also done in case the store base currency is ever changed. In this case, we need to re-process all orders again with the newly selected base currency.

The currency exchange rate background task will run once every 24 hours or after 20 seconds after an app pool recycle.

exchangeratesapi.io
fixer.io
currencylayer.com
dependency injection