By using this website you implicitly accept our cookies. For more informations read our Cookie policy
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 :)
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.
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!
Nerd alertThe 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
InfoYou can use the
currency
GET parameter to convert the currency of other resources, such as carts, orders, promotions and coupons.
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 |
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.
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 !