How to Globalize your eCommerce

In November, a new Locale feature was released to simplify globalization efforts for solutions where commerce spans across regions with different currencies and languages. Review this guide for the use case that matches your business most, and look at the examples for recommendations on how to model your solution.

Single Currency

If your business only operates in a single currency, and intends to remain with this single currency for the long haul, you can ignore the new Locale resource all together! Using Locales will add complexity to the set-up of your single-currency-site, so you can bypass the use of Locale to keep it simple.

When Locales are not used, all Price Schedules, Orders, Payment, and Transactions will have the Currency property set to null. This just means that the price associated with these objects is in the assumed currency for the implementation. If the business always operates in USD, the assumed currency is USD, if the business always operates in EUR, the assumed currency is EUR.

Multi-Currency with known Buyer Currencies (Profiled Buyers)

For eCommerce solutions that span across different regions with their own currencies, Locale will need to be used in combination with multiple User Groups or Buyers. If you know exactly who your Buyers are, and what currency they shop in, even better; this will simplify the set-up.

In the example below, we have a franchisor that has franchise locations in both US and Canada. This franchisor has a B2B eCommerce site where franchisees can buy supplies for the franchise location they own. The franchisor knows that their USA franchisees will shop in USD, and their Canada franchisees will shop in CAD.

User Group level Locale assignments:

You’ll see that separate User Groups represent each franchise location, but for simplicity of assignments, a User Group was also created to represent all USA locations and another one for all Canada locations. The USA and Canada User Groups are assigned to the Locale that aligns with each. Having the USA and Canada User Groups help limit the amount of Price Schedule > Party > Product assignments that need to be made to ensure products are showing in the correct currency to Buyers. Additionally, if a new franchise location opens, those users just need to be a part of the USA or Canada User Group to inherit all of the proper pricing in the correct currency.

Depending on your business requirements, it’s possible you can manage your Locales at the Buyer level instead of User Group level. Here is how that would look:

Buyer level Local assignments:

In either scenario, if I’m shopping as User 1, I will automatically be returned the $9.99 USD price, and if I’m User 5, I will automatically be returned the $11.99 CAD price.

Multi-Currency with Shopper Selected Currencies (Guest Shopping & Anonymous Buyers)

If your business offers guest shopping for public consumers, there will be an added level of complexity. Like the previous examples, multiple Buyers or User Groups need to be used, and in addition, Default Context Users are needed.

In the example below we have a direct Manufacture to Consumer B2C site. The manufacture sells products in Europe and sells to consumers across various countries (and currencies). They will not know who the consumer is until the consumer creates an account for purchasing.

User Group level Locale assignments:

Buyer level Local assignments:

In Anonymous shopping scenarios an API Client and related Default Context User need to be set-up. The Default Context User will need to be a part of a Buyer or User Group that has a Locale assignment. Then, build the UI to display the Locales that the shopper can switch between. They can then choose the Locale (currency) they want to shop in. If a user starts an order in one currency, but then switches to a new currency, the order will need to be recreated in the new currency (Patch Order.Currency functionally is not supported).

Payments & Transactions with Currency

When a Payment is created for an order, it will now inherit a Currency property with the same currency that is on the Order. This is the currency and price that the Buyer sees when they place their order. Transactions, on the other hand, have a Currency property that is not inherited; instead, it is writeable. This supports scenarios, such as the Marketplace Owner selling products in multi-currencies, but processing transactions in their single currency. In this case, the payment processor does the conversion, and that converted amount can be set on the Transaction in the converted currency.

Questions & Variations

Q: What if I know my Buyer’s currencies, but I still want to give them the opportunity to switch to another currency?

A: If you want to allow profiled users to change their own Locale you can build that into a middleware endpoint that moves the user between User Groups. The user will need to be removed from one User Group, and added to the other one (remember, a user existing two User Groups with different locales will yield unexpected pricing).

Q: What if some of my Buyers need to see a different price in the same currency?

A: No problem! This will require another Price Schedule and additional assignments. First, create another Price Schedule representing the Price and Currency you want. Then assign that Price Schedule to the specific User Group or Buyer (in this case, most likely it will be a User Group) that should see that price.

Remember that Pricing has an order of operations, and the most specific price assigned to the User will be the price that they see. Perhaps there is a Price set at the Buyer Level for a user, and also a different price set at the User Group level. The User Group level is more specific, so the Buyer User will see that price instead of the Buyer level price.

Let’s take a look at the added red components below. User 4 will see the $12.99 CAD price (assigned specifically to their User Group), instead of the $11.99 CAD price (assigned to the Buyer).

Q: How do I set a Default Locale or Currency for my buyers?

A: Setting a Default Locale can be done in a few different ways, and it is up to the implementer on how to handle it. Some may want to default the Locale based on a geo-location method, such as checking the Buyer’s IP address, and determining Locale from there. Another option is to hardcode the application to always authenticate new visitors as the Default Context User associated with your default Locale.

Q: Does Locale support auto-currency conversion?

A: The Locale feature supports allowing the Marketplace Owner or Supplier to set a unique product price in each currency (whether manually or integrated from another system). Locale is not meant to support auto-conversion use cases. The API-first nature of OrderCloud allows implementers to handle auto-currency conversion in the way that makes most sense for them and their customers if they prefer auto-conversion over setting a unique price per currency. We recommend keeping Locale null for cases where auto-currency conversion is used.

Still have questions?
Ask in our Community Channel

Content Powered By