• Log in
  • Contact Us

Get in touch  

Concepts • Currencies


Last updated: 01 Jul 2019

Use the currency settings to manage how the price formatting is localized.

Currency setting use cases

Use currency settings to:

  • Set up default currency
  • Enable/disable existing currency
  • Edit/delete existing currency
  • Set up multiple currency types

Set up currency

To set up a currency other than default, use Moltin dashboard or API.

Currency settings

Use the currency settings to manage how the price formatting is localized.

The formatted price can be found outside the regular price object for a product, in the meta object, which also includes timestamps, stock detail, etc.

Depending on localization, a common value for this field might be something like ${price}, if the currency is to be USD. Canadian French however, uses the symbol as a suffix, so in that case it would be {price}$.

Delete/disable currency

If a currency is no longer needed, you can delete it. Deleting destroys that currency object. The currency will be automatically deleted from all products that may have used it. If this was the only currency set up for the product, the product will have no currency, and if used in a request, the default currency will be used instead.

If a currency is no longer needed but you still want to retain it for for archiving purposes, disable it. Disabled currency will still show in the currency header, but it can’t be actively used.

Edit currency

Edit the currency through Moltin dashboard or API. Editing the existing currency will update all products that have that currency set up.

Display price vs. order price

When getting a list of orders, every order is displayed in the currency the order was taken in.

Default currency

Default currency is USD and it’s also enabled by default. You can set up any currency as default, just make sure the currency is enabled either through Moltin dashboard or API. Default currency is used as a fallback currency in a request, if not currency header is provided.

Multiple currency - key points:

  • You can configure several currency types for your project.
  • Carts don’t support multiple currency. If you add products with mixed currency, they will automatically fall back and use the default currency that is set up for these currency. Otherwise, display_price will be 0.

Using currencies header with products

Typically, when a request comes into a gateway, the currency settings are attached to the request based on the x-moltin-currency header the user passes in, or the project’s default if none is passed. The currency settings are responsible for adapting the price format to the currency in use.

For projects that support multiple currency, use the x-moltin-currencies header that contains the formatting detail for all currencies available to the project.

        "code": "GBP",
        "exchange_rate": 1,
        "format": "\u00A3{price}",
        "decimal_point": ".",
        "thousand_separator": ",",
        "decimal_places": 2
        "code": "USD",
        "exchange_rate": 0,
        "format": "${price}",
        "decimal_point": ".",
        "thousand_separator": ",",
        "decimal_places": 2

This allows you to have a collection of all currencies, including ones that are disabled.

How price is handled for orders

When the request gets to orders, the currency-related information from the header is put into the meta object of the response.

Price formatting

Price formatting is handled by Moltin. Once a cart converts into an order, the header provides all formatting details available for the currency specified in the order. If the currency doesn’t exist in the project, then currencies. GET will return sensible defaults, so the display_price values won’t be formatted, but the correct order currency will be displayed.

Further reading

Explore More Concepts

01 Jul 2019

How to calculate cart and order totals

There are two methods that may be used to calculate cart and order totals. The method used depends on the calculation_method setting. The default is currently the simple method and this will continue...

Read More
James Carter
in Orders | Carts
18 Jun 2019

How promotions work

Promotions allow you to provide discounts to customers. By defining a Promotion and a code, you put in place the facility to offer discounts to customers applied directly to their shopping carts.

Read More
George FitzGibbons
in Carts | Promotions
06 Jun 2019

When to use a custom cart

Custom carts allow you to process an order for any type of item you wish to sell. The item does not need to exists in Moltin, which means custom cart items can be used for all sort of use cases.

Read More
George FitzGibbons
in Carts