External Methods
Localize Price
Convert prices from the native currency to the currently selected currency.
This method uses the currently selected country and currency rules.
Input priceDetails object
{
"Price": 19.95,
"ProductClassCoefficient": 1.05,
"Quantity": 1
}Example
var priceDetails = {
"Price": 19.95,
"ProductClassCoefficient": 1.05,
"Quantity": 1
};
var callback = function(localizedPrice) {
console.log(JSON.stringify(localizedPrice));
};
GEM_Components.ExternalMethodsComponent.LocalizePrice(priceDetails, callback);Field Name | Type | Optional | Description |
|---|---|---|---|
| number | No | The single price of a product, to be converted. |
| number | Yes | The product class coefficient to be used in this price conversion. Use null if the product does not have a product class. |
| number | No | The quantity of the product to be converted. If no value is provided, a default value of 1 is used. |
| boolean | Yes | If the field is true, the converted price will not be rounded. Do not provide this field if rounding is required. |
Note
Due to rounding rules, the individual product price must be used for the price parameter, not the line item subtotal.
Returned localizedPrice object
{
"ConvertedPrice": 34.99,
"SymboledPrice": "€34.99",
"CurrencySymbol": "€"
}Field Name | Type | Description |
|---|---|---|
| number | The converted price’s value. |
| string | The converted price, formatted for the selected currency |
| string | The currently selected currency symbol. |
De-localize Converted Price
Convert the customer's local currency back to the original currency.
This method uses the rules from the current country and currency in the calculation.
Example
var priceDetails = {
"Price": 100,
"ProductClassCoefficient": 1.05,
"Quantity": 1
};
var callback = function(delocalizedPrice) {
console.log(JSON.stringify(delocalizedPrice));
};
GEM_Components.ExternalMethodsComponent.DelocalizePrice(priceDetails, callback);Note
Refer to LocalizePrice method to view the structure of the priceDetails and delocalizedPrice objects. The delocalizedPrice object is structured the same as the localizedPrice object.
Format Converted Price
Format an already converted price, using the currently selected currency.
Input convertedPriceDetails object
{
"ConvertedPrice" = 60
}Field Name | Type | Description |
|---|---|---|
| number | The converted price, to be formatted using the selected currency. |
Returned formattedPrice object
{
"SymboledPrice": "€60.00",
"CurrencySymbol": "€"
}Field Name | Type | Description |
|---|---|---|
| string | The converted price, formatted for the selected currency. |
| string | The currently selected currency symbol. |
Is Operated by Global-e
Check if the currently selected shipping destination country is a Global-e-operated country.
Example
var callback = function(isOperated) {
console.log(isOperated);
};
GEM_Components.ExternalMethodsComponent.IsOperatedByGlobalE(callback);Get Checkout URL
Get the checkout URL that you want to direct customers to.
urlParams is a JSON object with a single CartToken string parameter. If you have a headless Shopify site, use the ShopifyCheckoutId instead of the CartToken.
Example
var urlParams = {
CartToken: "customer cart token"
};
var callback = function(url) {
console.log(url);
};
GEM_Components.ExternalMethodsComponent.GetCheckoutUrl(urlParams, callback);Update Cart
Receive a notification when the cart needs to be updated on the client side, using this latest cartData that is passed in.
Example
var cartData = { }; // get cart data.
GEM_Components.ExternalMethodsComponent.UpdateCart(cartData);The following events trigger this method:
A product is added to the cart
A product is removed from the cart
The quantity of a product is changed
The cart is shown to the user
cartData
cartData is a JSON object that matches a specific schema.
Example
{
"productsList": [
{
"Name": "Red Shoes",
"CartItemId": "abcd-1234-qwe",
"OrderedQuantity": 1,
"OriginalListPrice": 20,
"OriginalSalePrice": 15.95
}
],
"discountsList": [
{
"Name": "10% off",
"OriginalDiscountValue": 1.59,
"ProductCartItemId": "abcd-1234-qwe"
}
]
}productsList
productsList is an array of product objects, detailed below:
Field Name | Type | Description |
|---|---|---|
| string | The name of the discount. |
| number | The value of the discount, in your native currency. This value is converted to the customer’s selected currency |
| string | The |
User Localization
Instead of directly reading and setting the GlobalE_Data cookie, you can use the GetUserLocalization and SetUserLocalization external methods.
GetUserLocalization
Example
var callback = function(userLocalization) { console.log(JSON.stringify(userLocalization)); }; GEM_Components.ExternalMethodsComponent.GetUserLocalization(callback);
Description
Invoke this method to retrieve the user’s current locale, represented by the following object:
Example Response
{
"Country": {
"Code":"SE"
},
"Currency": {
"Code":"SEK" }
}
}Country
Field Name | Type | Description |
|---|---|---|
|
| The two-character ISO 3166-1 Alpha-2 Country Code for the current country |
Currency
Field Name | Type | Description |
|---|---|---|
|
| The three-character ISO 4217 Currency Code for the current currency |
SetUserLocalization
Important
Invoking this method refreshes the page.
Example
var userLocalization = {
"CountryCode":"SE",
"CurrencyCode":"SEK"
};
GEM_Components.ExternalMethodsComponent.SetUserLocalization(userLocalization);Description
Invoke this method to set the GlobalE_Data cookie on your domain with the arguments provided. Once called, the page will immediately be refreshed so that the cookie setting takes effect.
Field Name | Type | Description |
|---|---|---|
|
| The two-character ISO 3166-1 Alpha-2 Country Code for the current country |
|
| The three-character ISO 4217 Currency Code for the currency |
Troubleshooting failed code
If you attempted to use a GEM external method and the code failed, this could be because the GEM module has not loaded yet.
In this situation, you can use an ExternalEventsComponent
With the ExternalEventsComponent you can set a function on the window object and Global-e's code executes that function when a certain event is triggered.
We recommend that you listen for the GlobalE_Loaded event before executing the code. To do this, set the below function on the window object and the code will be executed when the GEM solution loads.
Example
window['GlobalE_Loaded'] = function() {
//add code here
}