| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| v:2.0:multicurrency [2016/10/06 06:53] – adam | v:2.0:multicurrency [2020/04/21 17:30] (current) – [MultiCurrency and Discounts] marija |
|---|
| ====== Multi-Currency Support in FoxyCart ====== | ====== Multi-Currency Support in FoxyCart ====== |
| |
| <WRAP info>__**Advanced Functionality**__ This functionality is currently available upon request. Please [[http://www.foxycart.com/contact|email us]] to have multi-currency turned on for your store.</WRAP> | |
| |
| ===== How Multi-Currency Functionality works in FoxyCart ===== | ===== How Multi-Currency Functionality works in FoxyCart ===== |
| 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. | FoxyCart includes multi-currency in a couple ways - both changing the currency of the whole cart and dynamically converting a price from one currency to another. |
| |
| There are two parameters that you can use to handle transactions in different currencies: | There are two parameters that you can use to handle transactions in different currencies: ''template_set'' and ''price''. |
| * ''template_set'' is passed through as a session-wide variable, as the code of the respective template set as specified in the administration. See the [[v:2.0:template_sets|template sets section]] for more information. | |
| * ''price'', appended with a [[http://en.wikipedia.org/wiki/ISO_4217#Active_codes|3-character ISO currency code]], eg: ''&price=15.99usd'' | |
| |
| The ''template_set'' 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 ''template_set'' to one with a different locale that the cart is currently set to will empty the cart**. You can, however, add products in the same request that you change the ''template_set'', and they'll be added appropriately. | ==== template_set: session wide locale setting ==== |
| |
| If a product is added in a currency that does not match the current locale of the cart (for example, with a store that is set to USD by default, and a product is added to the cart as ''price=50mxn''), the products price will be dynamically converted to the cart currency. The rate used in the conversion is requested from [[http://openexchangerates.org|openexchangerates.org]]. | The [[v:2.0:template_sets|template set]] paramater is passed through as a session-wide variable, as the code of the respective template set as specified in the administration, such as ''&template_set=fr''. The template set is not product specific, but changes the currency (and also possibly language) for the customer's entire cart for that session. View the [[v:2.0:template_sets|template set]] page for details on adding and using the sets for your store. |
| | |
| | By default, new customers will see a cart in your store's default locale, as set in the ''DEFAULT'' template set (or alternatively from the "store locale" setting on the store's setting page). |
| | |
| | You can specify a template set with a normal call to your store's ''/cart'' endpoint. Note that changing the ''template_set'' to one with a different locale than the cart is currently set to will empty the cart. You can however add products in the same request that you change the ''template_set'', and they'll be added appropriately. |
| | |
| | ==== price: per product with currency code appended ==== |
| | |
| | The currency for a specific product can also be set by appending the 3-character ISO currency code, eg: ''&price=15.99usd'' |
| | |
| | If a product is added in a currency that does not match the current locale of the cart (for example, with a store that is set to USD, and a product is added to the cart as ''price=50mxn''), the products price will be dynamically converted to the cart currency. If no currency code is appended to a product's price, it will be assumed as the store's default currency, and dynamically converted from that to the current currency of the cart. |
| | |
| | Dynamic price conversions currently require that a store have at least two different template sets with differing locales be configured. The rate used in the conversion is requested from [[http://openexchangerates.org|openexchangerates.org]]. |
| |
| ==== Product Option Modifiers ==== | ==== Product Option Modifiers ==== |
| </code> | </code> |
| |
| This syntax is the same for category discounts and for coupons. This allows setting custom discounts per currency. <wrap tip>If a currency is not included, the discount will not apply.</wrap> This is to prevent discounts from applying that could have significantly wrong values after the conversion math is done. | This syntax is the same for category discounts and for coupons, except you'll put the JSON right in the //coupon// or //discount details// input. This allows setting custom discounts per currency. <wrap tip>If a currency is not included, the discount will not apply.</wrap> This is to prevent discounts from applying that could have significantly wrong values after the conversion math is done. |
| |
| ==== Some Examples of MultiCurrency Usage ==== | ==== Some Examples of MultiCurrency Usage ==== |
| Let's assume your store's default template set's 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: | Let's assume your store's default template set's 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: |
| <code html> | <code html> |
| <a href="https://foxycart-demo.foxycart.com/cart?name=$50 MXN Product without locale&price=50mxn&code=a33938"> | <a href="https://foxycart-demo.foxycart.com/cart?name=$50 MXN Product without template set&price=50mxn&code=a33938"> |
| $50 MXN, no template set | $50 MXN, no template set |
| </a> | </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 create a template set that specifies the Mexican locale, and pass in the ''template_set'' value as it's code, like below. Note that this would clear the cart's contents //if// the cart was previously in a different currency. | 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 create a template set that specifies the Mexican locale, and pass in the ''template_set'' value as it's code, like below. Note that this would clear the cart's contents //if// the cart was previously in a different currency. |
| <code html> | <code html> |
| <a href="https://foxycart-demo.foxycart.com/cart?name=$50 MXN Product without locale&price=50mxn&code=a33938&template_set=mx"> | <a href="https://foxycart-demo.foxycart.com/cart?name=$50 MXN Product with template set&price=50mxn&code=a33938&template_set=mx"> |
| $50 MXN, es_MX locale | $50 MXN, es_MX locale template set |
| </a> | </a> |
| </code> | </code> |
