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

Name	Code	Symbol
US Dollar	USD	$
Canadian Dollar	CAD	CA$
Euro	EUR	€
United Arab Emirates Dirham	AED	AED
Afghan Afghani	AFN	Af
Albanian Lek	ALL	ALL
Armenian Dram	AMD	AMD
Argentine Peso	ARS	AR$
Australian Dollar	AUD	AU$
Azerbaijani Manat	AZN	man.
Bosnia-Herzegovina Convertible Mark	BAM	KM
Bangladeshi Taka	BDT	Tk
Bulgarian Lev	BGN	BGN
Bahraini Dinar	BHD	BD
Burundian Franc	BIF	FBu
Brunei Dollar	BND	BN$
Bolivian Boliviano	BOB	Bs
Brazilian Real	BRL	R$
Botswanan Pula	BWP	BWP
Belarusian Ruble	BYR	BYR
Belize Dollar	BZD	BZ$
Congolese Franc	CDF	CDF
Swiss Franc	CHF	CHF
Chilean Peso	CLP	CL$
Chinese Yuan	CNY	CN¥
Colombian Peso	COP	CO$
Costa Rican Colón	CRC	₡
Cape Verdean Escudo	CVE	CV$
Czech Republic Koruna	CZK	Kč
Djiboutian Franc	DJF	Fdj
Danish Krone	DKK	Dkr
Dominican Peso	DOP	RD$
Algerian Dinar	DZD	DA
Estonian Kroon	EEK	Ekr
Egyptian Pound	EGP	EGP
Eritrean Nakfa	ERN	Nfk
Ethiopian Birr	ETB	Br
British Pound Sterling	GBP	£
Georgian Lari	GEL	GEL
Ghanaian Cedi	GHS	GH₵
Guinean Franc	GNF	FG
Guatemalan Quetzal	GTQ	GTQ
Hong Kong Dollar	HKD	HK$
Honduran Lempira	HNL	HNL
Croatian Kuna	HRK	kn
Hungarian Forint	HUF	Ft
Indonesian Rupiah	IDR	Rp
Israeli New Sheqel	ILS	₪
Indian Rupee	INR	Rs
Iraqi Dinar	IQD	IQD
Iranian Rial	IRR	IRR
Icelandic Króna	ISK	Ikr
Jamaican Dollar	JMD	J$
Jordanian Dinar	JOD	JD
Japanese Yen	JPY	¥
Kenyan Shilling	KES	Ksh
Cambodian Riel	KHR	KHR
Comorian Franc	KMF	CF
South Korean Won	KRW	₩
Kuwaiti Dinar	KWD	KD
Kazakhstani Tenge	KZT	KZT
Lebanese Pound	LBP	LB£
Sri Lankan Rupee	LKR	SLRs
Lithuanian Litas	LTL	Lt
Latvian Lats	LVL	Ls
Libyan Dinar	LYD	LD
Moroccan Dirham	MAD	MAD
Moldovan Leu	MDL	MDL
Malagasy Ariary	MGA	MGA
Macedonian Denar	MKD	MKD
Myanma Kyat	MMK	MMK
Macanese Pataca	MOP	MOP$
Mauritian Rupee	MUR	MURs
Mexican Peso	MXN	MX$
Malaysian Ringgit	MYR	RM
Mozambican Metical	MZN	MTn
Namibian Dollar	NAD	N$
Nigerian Naira	NGN	₦
Nicaraguan Córdoba	NIO	C$
Norwegian Krone	NOK	Nkr
Nepalese Rupee	NPR	NPRs
New Zealand Dollar	NZD	NZ$
Omani Rial	OMR	OMR
Panamanian Balboa	PAB	B/.
Peruvian Nuevo Sol	PEN	S/.
Philippine Peso	PHP	₱
Pakistani Rupee	PKR	PKRs
Polish Zloty	PLN	zł
Paraguayan Guarani	PYG	₲
Qatari Rial	QAR	QR
Romanian Leu	RON	RON
Serbian Dinar	RSD	din.
Russian Ruble	RUB	RUB
Rwandan Franc	RWF	RWF
Saudi Riyal	SAR	SR
Sudanese Pound	SDG	SDG
Swedish Krona	SEK	Skr
Singapore Dollar	SGD	S$
Somali Shilling	SOS	Ssh
Syrian Pound	SYP	SY£
Thai Baht	THB	฿
Tunisian Dinar	TND	DT
Tongan Paʻanga	TOP	T$
Turkish Lira	TRY	TL
Trinidad and Tobago Dollar	TTD	TT$
New Taiwan Dollar	TWD	NT$
Tanzanian Shilling	TZS	TSh
Ukrainian Hryvnia	UAH	₴
Ugandan Shilling	UGX	USh
Uruguayan Peso	UYU	$U
Uzbekistan Som	UZS	UZS
Venezuelan Bolívar	VEF	Bs.F.
Vietnamese Dong	VND	₫
CFA Franc BEAC	XAF	FCFA
CFA Franc BCEAO	XOF	CFA
Yemeni Rial	YER	YR
South African Rand	ZAR	R
Zambian Kwacha	ZMK	ZK

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.