Enabling multi-currency for your store doesn't change anything by default. The price parameter still defaults to your store's default currency, as specified in your store's “settings” page. This is important to note, as FoxyCart will interpret prices without a currency code in this way.

There are two parameters that you can use to handle transactions in different currencies:

• locale is passed through as a session-wide variable.
• price, appended with a 3-character ISO currency code.

The locale is not product specific, but rather changes the currency for the customer's cart, for that session. By default for new customers it will be your store's configured locale. You can set it with a normal call to your /cart endpoint. Note that changing the locale will empty the cart. You can, however, add products in the same request that you change the locale, and they'll be added appropriately.

If your gateway supports multiple currencies on a single account, great! You're all set. If you need one set of credentials (username/password/ID/transaction key/etc) per currency, you can enter them like this:

{"USD": "x39gA5Me2K", "GBP": "9s77FvP6ts"}

A few things to note:

• Even if your username or password is an integer, you must wrap it in double quotes.
• If a currency code match isn't found (like if the cart is in SGD but you don't have an SGD value in your credential string), FoxyCart will attempt to submit the transaction using the first value in the list. (So it'd use the x39gA5Me2K in the example above.)
• The string must be formatted as valid JSON, and cannot exceed 500 characters total.
• Not all gateways support multi-currency. Check this page to see the currently supported gateways, and if you don't see your gateway on this list, please get in touch with us to discuss the possibility of adding support.

Product discounts, category discounts, and coupon codes can all handle multi-currency functionality with some different syntax. Please make sure you familiarize yourself with how coupons and discounts work before continuing.

For multi-currency discounts, you can use syntax like this:

&discount_quantity_amount=bogo 100{"discount_type": "repeat", "USD": "2-10", "MXN": "2-150"}

A few things to note. First, the syntax must be valid JSON, so that means double quotes around all the values. Second (and because of the double quotes), you must URL encode this string, or you must wrap the whole thing in single quotes instead of double quotes. Otherwise the double quotes will get in the way of your valid HTML.

For a form input it'll look very similar:

<form action="https://foxycart-demo.foxycart.com/cart">
	<input type="hidden" name="name" value="975mxn bogo 2">
	<input type="hidden" name="price" value="975MXN">
	<input type="hidden" name="code" value="abc130">
	<!-- Note that we're using single quotes on the next value,
		 because form inputs don't handle URL encoding -->
	<input type="hidden" name="discount_quantity_amount" 
		value='bogo 100{"discount_type": "repeat", "USD": "2-10", "MXN": "2-150"}'>
	<input type="submit">
</form>

This syntax is the same for category discounts and for coupons. This allows setting custom discounts per currency. If a currency is not included, the discount will not apply. This is to prevent discounts from applying that could have significantly wrong values after the conversion math is done.

Let's assume your store's default locale is en_US, so it will be using the USD $. A customer sees a price in Mexican pesos (MXN). The customer adds the product to the cart, and the values in MXN will convert to USD:

<a href="https://foxycart-demo.foxycart.com/cart?name=$50 MXN Product without locale&price=50mxn&code=a33938">
	$50 MXN, no locale
</a>

Let's say you wanted to add that product to the cart in MXN Pesos, instead of having it convert to the default (or current) currency. You'd simply pass in the locale value, like below. Note that this would clear the cart's contents if the cart was previously in a different currency.

<a href="https://foxycart-demo.foxycart.com/cart?name=$50 MXN Product without locale&price=50mxn&code=a33938&locale=es_MX">
	$50 MXN, es_MX locale
</a>

At this point, if you added a product in a different currency (or without a currency code in the price value), the price would be converted to MXN Pesos.

One common use case would be to set the currency on pageload, perhaps if the customer clicks a link or lands on a specific subdomain. To create a link that sets the locale silently (ie. it sets the FoxyCart session but doesn't take them to the cart), it'd look like this (with a callback):

<a id="locale-mxn" href="javascript:;">Set locale to MXN in the background</a>
<script>
	document.getElementById('locale-mxn').onclick = function(){
		FC.client.request('https://'+FC.settings.storedomain+'/cart?locale=mxn')
		.done(function(data){
			console.log(data.locale_info.int_curr_symbol);
		});
	};
</script>