By using this website you implicitly accept our cookies. For more informations read our Cookie policy

Work with currencies

With Marketcloud your store can support multiple currencies, allowing you to show prices and checkouts in multiple currencies.

Warning
The currencies feature is still in beta, if you find any bug or have questions, don't hesitate to let us know :)

Table of contents

  1. Set a base currency
  2. Support multiple currencies
  3. Show prices in other currencies
  4. Checkout and payments

Set a base currency

Every application in Marketcloud has a base currency. This is the currency used when entering the price of your products and it is used as default when no currency is specified during checkout and when requesting information from the API. Most stores will do just fine with one single currency, but others will sell their products in other cuntries. To set your basic currency, open your dashboard and click on your app's backoffice.
Once your store's dashboard is loaded. click on System > Settings > Basic information, here you can find the currency section to set your base currency. Once you selected the basic currency for your store, remember to save your changes.

Important
The base currency is the one used internally to represent base prices. These basic values are then used to translate prices and fees in other currencies.

Support multiple currencies

Sometimes one currency is not enough, maybe the store wants to sell products in another country which requires to show prices and in another currency. For this kind of situations you can add multiple currencies to your store.

To add multiple currencies, open your dashboard and click on your app's backoffice.
Once your store's dashboard is loaded. click on System > Localization > Currencies, here you can find the currency section to add additional currencies for your store.

Warning
In order to be able to show prices in other currencies you must add each currency in this section with the most appropriate rate. We provide a fetch rate functionality that grabs the current value from various financial systems, but this rate will not refresh automatically!

Show prices in other currencies

Nerd alert

The following paragraph is meant for developers, so if you're not a developer and it doesn't make any sense to you, don't worry! The developer(s) building your store will surely understand this :)

Once we added both base and additional currencies in our store we are ready to display our products prices in the correct currency.

Retrieving products in a particular currency is as easy as setting a GET parameter named currency and setting it to one of the supported currency codes.

Suppose we want to retrieve our products and our customer selected US Dollars as currency, all we have to do to show converted prices is:

curl -XGET https://api.marketcloud.it/v0/products?currency=USD
Info

You can use the currency GET parameter to convert the currency of other resources, such as carts, orders, promotions and coupons.

Supported presentment currencies
NameCodeSymbol
US DollarUSD$
Canadian DollarCADCA$
EuroEUR
United Arab Emirates DirhamAEDAED
Afghan AfghaniAFNAf
Albanian LekALLALL
Armenian DramAMDAMD
Argentine PesoARSAR$
Australian DollarAUDAU$
Azerbaijani ManatAZNman.
Bosnia-Herzegovina Convertible MarkBAMKM
Bangladeshi TakaBDTTk
Bulgarian LevBGNBGN
Bahraini DinarBHDBD
Burundian FrancBIFFBu
Brunei DollarBNDBN$
Bolivian BolivianoBOBBs
Brazilian RealBRLR$
Botswanan PulaBWPBWP
Belarusian RubleBYRBYR
Belize DollarBZDBZ$
Congolese FrancCDFCDF
Swiss FrancCHFCHF
Chilean PesoCLPCL$
Chinese YuanCNYCN¥
Colombian PesoCOPCO$
Costa Rican ColónCRC
Cape Verdean EscudoCVECV$
Czech Republic KorunaCZK
Djiboutian FrancDJFFdj
Danish KroneDKKDkr
Dominican PesoDOPRD$
Algerian DinarDZDDA
Estonian KroonEEKEkr
Egyptian PoundEGPEGP
Eritrean NakfaERNNfk
Ethiopian BirrETBBr
British Pound SterlingGBP£
Georgian LariGELGEL
Ghanaian CediGHSGH₵
Guinean FrancGNFFG
Guatemalan QuetzalGTQGTQ
Hong Kong DollarHKDHK$
Honduran LempiraHNLHNL
Croatian KunaHRKkn
Hungarian ForintHUFFt
Indonesian RupiahIDRRp
Israeli New SheqelILS
Indian RupeeINRRs
Iraqi DinarIQDIQD
Iranian RialIRRIRR
Icelandic KrónaISKIkr
Jamaican DollarJMDJ$
Jordanian DinarJODJD
Japanese YenJPY¥
Kenyan ShillingKESKsh
Cambodian RielKHRKHR
Comorian FrancKMFCF
South Korean WonKRW
Kuwaiti DinarKWDKD
Kazakhstani TengeKZTKZT
Lebanese PoundLBPLB£
Sri Lankan RupeeLKRSLRs
Lithuanian LitasLTLLt
Latvian LatsLVLLs
Libyan DinarLYDLD
Moroccan DirhamMADMAD
Moldovan LeuMDLMDL
Malagasy AriaryMGAMGA
Macedonian DenarMKDMKD
Myanma KyatMMKMMK
Macanese PatacaMOPMOP$
Mauritian RupeeMURMURs
Mexican PesoMXNMX$
Malaysian RinggitMYRRM
Mozambican MeticalMZNMTn
Namibian DollarNADN$
Nigerian NairaNGN
Nicaraguan CórdobaNIOC$
Norwegian KroneNOKNkr
Nepalese RupeeNPRNPRs
New Zealand DollarNZDNZ$
Omani RialOMROMR
Panamanian BalboaPABB/.
Peruvian Nuevo SolPENS/.
Philippine PesoPHP
Pakistani RupeePKRPKRs
Polish ZlotyPLN
Paraguayan GuaraniPYG
Qatari RialQARQR
Romanian LeuRONRON
Serbian DinarRSDdin.
Russian RubleRUBRUB
Rwandan FrancRWFRWF
Saudi RiyalSARSR
Sudanese PoundSDGSDG
Swedish KronaSEKSkr
Singapore DollarSGDS$
Somali ShillingSOSSsh
Syrian PoundSYPSY£
Thai BahtTHB฿
Tunisian DinarTNDDT
Tongan PaʻangaTOPT$
Turkish LiraTRYTL
Trinidad and Tobago DollarTTDTT$
New Taiwan DollarTWDNT$
Tanzanian ShillingTZSTSh
Ukrainian HryvniaUAH
Ugandan ShillingUGXUSh
Uruguayan PesoUYU$U
Uzbekistan SomUZSUZS
Venezuelan BolívarVEFBs.F.
Vietnamese DongVND
CFA Franc BEACXAFFCFA
CFA Franc BCEAOXOFCFA
Yemeni RialYERYR
South African RandZARR
Zambian KwachaZMKZK

Checkout and payments

Until now we were just reading resources with different currencies, but what about orders and payments?

The first thing to keep in mind is that order creation and payment are two separate processes. When you create an order through Marketcloud's API, you are putting together several instances of resources such as products, coupons, users and carts and turning them into something more valuable for your store, an order. This order will keep an internal snapshot of the state of those ingredients used to create it. This is because you want to know exactly which was the price you sold the product for when reviewing an order.

This internal snapshot of resources uses the base currency to represent those values! So that you can always have a precise value for each order.


 marketcloud.orders.create({
  "cart_id"             : 1234,
  "shipping_address_id" : 12345,
  "user_id"             : 123456,
  "currency"            : "USD"
 })
 .then( (response) => {
  let order = response.data;
 })

In the previous example, the created order will be something like this:

  {
  "items": [
    { ... }
  ],
  "shipping_address": { ... },
  "billing_address": { ... },
  "shipping": { ... },
  "taxes": [
    {...}
  ],
  "cart_id": 1234,
  "shipping_id": 1234,
  "products": [
  { ... }
  ],
  "items_total": 15,
  "shipping_total": 10,
  "taxes_total": 4.3,
  "total": 29.3,
  "created_at": 1502960471492,
  "status": "processing",
  "payment_method": "StripeMethod",
  "promotion_id": 0,
  "currency": {
    "symbol": "$",
    "name": "US Dollar",
    "symbol_native": "$",
    "decimal_digits": 2,
    "rounding": 0,
    "code": "USD",
    "name_plural": "US dollars",
    "rate": 1.17
  },
  "id": 123,
  "payments": [
    { ... }
  ],
  "display_items_total": "15 EUR",
  "display_total": "29.3 EUR"
}
    
  

As you can see the internal state of the order is still displayed in the base currency.

When creating the payment, if the order was created with a specific currency, the payment method will have to translate the amount.

Example
In your online store you have EUR as base currency and USD as optional currency, a customer from the United States is browsing your store and he is able to see prices in USD thanks to the currency settings.
The customer decides to buy an article from the store, you will use Marketcloud's API to create an order instance setting the currency to USD.
The internal state of the order will keep all values in EUR because it's the base currency, but you are able to display order totals and subtotals in USD.

Warning
Not every payment integration supporting automatic multi currency handling.Stripe does but, for example, with Braintree you would need different merchant accounts and the most common thing to do is to charge the card in your base currency.

Questions?

We're super happy to help with any question you might have! Send us an email, or get in touch with us in our Slack channel !