1. Globalization

Globalization for marketplaces

New features to enable configuration of multi-currency and multi-language marketplaces. These features provide comprehensive support for global commerce operations.

Locale resource

json
{
  "ID": "en-US-USD",
  "Currency": "USD",
  "Language": "en-US"
}

The Locale resource is assignable to Buyers and Buyer User Groups. Both Currency and Language are string properties with a maximum length of 100. We recommend using ISO-4217 currency codes and ISO-639-1 language code - ISO-3166 Country Codes respectively for compatibility with other platforms such as payment processors, tax calculation services, and content management systems. The ID property is writable and follows the same convention as all other writable IDs in OrderCloud.

Key points:

  • The Language property will not control any OrderCloud behavior, but is provided to make the process of building a multi-language UI easier for the developer.
  • The Currency property will impact several OrderCloud behaviors (outlined below).
  • A Locale object will be returned on both the User resource and the MeUser resource. If no Locale is assigned, the object will be null.

Important rules:

  • Only ever assign one Locale per party (Buyer or UserGroup). Assigning multiple to the same party is considered a misconfiguration and will yield unexpected results.
  • A Locale object will be returned on both the User resource and the MeUser resource. If no Locale is assigned, the object will be null.

Locale will drive several behaviors around products and ordering:

  • A user will only see product pricing in the Currency from their assigned Locale. If no Locale is assigned, they will only be able to view pricing where Currency is null.
  • A user will only be able to create a LineItem if the LineItem.Product has pricing available in the Currency from their assigned Locale. If no Locale is assigned, they will only be able to create a LineItem if the LineItem.Product has pricing available where Currency is null.
  • A user will only be able to create and submit an Order with a Currency from their assigned Locale. If a user's Locale changes between the time an Order is created and submitted, submitting the order will fail.

API endpoints

  • GET v1/locales/{localeID}
  • GET v1/locales
  • POST v1/locales
  • PUT v1/locales
  • PATCH v1/locales/{localeID}
  • DELETE v1/locales/{localeID}
  • GET v1/locales/assignments
  • POST v1/locales/assignments
  • DELETE v1/locales/{localeID}/assignments

New properties

Order.Currency

  • Read-only
  • Inherits from Order.FromUser's Locale
  • Null if no Locale assigned

Payment.Currency

  • Read-only
  • Inherits from Order.Currency

Payment.Transaction.Currency

  • Writable, can be null
  • Can be used when you have multiple currencies in the same payment. For example, the presentment currency (currency of the charge to the customer) could be different than the settlement currency (currency of the destination account).

PriceSchedule.Currency

  • Writable, can be null
  • Calling POST v1/products/assignments with a PriceScheduleID will require that the party being assigned has a Locale with a Currency that matches the PriceSchedule.
  • Modifying Currency on a PriceSchedule will first do a check to ensure it is not assigned to any parties, and will throw an error if so.

User.Locale

  • Read-only
  • Helpful for displaying correct information in the UI based on a user's Language and/or Currency
If you have suggestions for improving this article, let us know!