Storefront Modifications
To enable Bespoke front-end functionality on your site, place the GEM Code Snippet, a small JavaScript and CSS code snippet as part of your site's header as detailed in the following sections.
The GEM JavaScript
Below is a suggested way of loading the Bespoke JavaScript library asynchronously on your site:
<script>
(function () {
var s = document.createElement('script');
s.type = 'text/javascript';
s.async = true;
s.src = '//gepi.bglobale.com/proxy/get/[MID]';
document.getElementsByTagName('head')[0].appendChild(s);
})();
</script>Using the above snippet will ensure that the Bespoke JavaScript module will load asynchronously and will not block your current page rendering.
Note
The [MID] at the end of the URL should be replaced with the merchant ID provided to you by Global-e.
The Global-e Module CSS
As mentioned above, the Bespoke CSS should be placed on your site’s header, as shown below:
<head>
…
<link id="GEPIStyles" rel="stylesheet" href="//gepi.bglobale.com/proxy/css/[MID]">
</head>
Note
The [MID] at the end of the URL should be replaced with the merchant ID provided to you by Global-e.
Alternative Methods
Tag Managers – if your site uses a tag manager library, it is possible to load the Global-e Module JavaScript via your current tag manager. In doing so, please ensure that the Global-e Module JavaScript library is given the highest priority in your tag manager, for the reasons mentioned above.
Note - The Global-e Module CSS link should not be loaded via a tag manager in any way.
CSS on Site – The Global-e Module CSS logic may be implemented directly on your own server. The logic would then be as follows: when the Global‑e server identifies the customer browsing the CSS as coming from a Global‑e-operated country, the Global‑e server returns a valid CSS that contains the relevant CSS content for your site. Alternatively, when the Global‑e server identifies the customer as coming from a country not operated by Global‑e, then the CSS returns empty.
This way, Global-e’s CSS does not affect customers browsing from countries not operated by Global-e, even in case the Global-e Module JavaScript was not loaded for some reason.
For merchants wishing to implement such logic, Global‑e sends the CSS content to be placed on the merchant site.
Product-specific VAT Rates in the EU and Restrictions
Bespoke can fully support the handling of product “country exceptions” that are applicable to a specific country.
When shipping inside the EU and distance selling is applicable, by default Bespoke will enforce the
respective shipping country’s standard (maximum) VAT rate when calculating product prices. However, in most EU countries, there are certain categories of products that allow a non-standard (reduced) VAT rate defined in this country to be applied.
Another sample of a product “country exceptions” is product restrictions in a certain country. These can be either defined by the merchant for commercial reasons (e.g. brand or category restrictions) or by Global‑e for regulatory reasons (e.g. products containing some furs when shipping to Australia). By default, product restrictions will be enforced when the user gets to Global‑e checkout.
In order to support product “exceptions”, such as reduced product VAT rates in the EU and restrictions applied when browsing the merchant’s site (before the user gets to Global‑e checkout), Bespoke needs to be able to read this information embedded within the DOM.
The respective “exceptions” data can be indicated in the data-countries data attribute for these products.
Below are 2 examples of how the “country exceptions” data attribute should appear on the website:
<div data-countries="{"IT" : {"restricted" :" true, "vat" : 10.0}, "US" {"restricted" : true}, "DE" : {"vat" : 7.0}}"></div>In the sample above, the product will be restricted in Italy and in the US and will have reduced VAT in Italy and Germany.
<div data-countries="{"all" : {"forbidden" : true}, "DE" : {"vat" : 7.0}}"></div>In the sample above, the product will be completely forbidden in all countries operated by Global‑e and will have reduced VAT in Germany.
This information can be loaded by the merchant site’s back end from Global-e by periodically calling RecentProductCountryS API mentioned in the separate “Global-e API” document. Alternatively, the merchant may choose to render only commercial restrictions in the data-countries data attribute, in which case the default GEM behavior will still be preserved for the rest.
Reduced VAT Rate Support
For merchants having reduced VAT rate products in the catalog(e.g. Children Clothing for the UK merchants), the applicable reduced VAT rate can be indicated in the data-product-vat data attribute for these products. The bespoke script will take the specified VAT rate into consideration when calculating the price for the customer.
Below is an example of how the VAT rate data attribute should appear on the website:
<div data-product-vat="0">...</div>
<div data-product-vat="20">...</div>
Product-specific VAT Rates in the EU and Restrictions
Bespoke can fully support the handling of product “country exceptions” that are applicable to a specific country.
When shipping inside the EU and distance selling is applicable, by default Bespoke will enforce the respective shipping country’s standard (maximum) VAT rate when calculating product prices. However, in most EU countries, there are certain categories of products that allow a non-standard (reduced) VAT rate defined in this country to be applied.
Another sample of a product “country exceptions” is product restrictions in a certain country. These can be either defined by the merchant for commercial reasons (e.g. brand or category restrictions) or by Global-e for regulatory reasons (e.g. products containing some furs when shipping to Australia). By default, product restrictions will be enforced when the user gets to Global-e checkout.
In order to support product “exceptions”, such as reduced product VAT rates in the EU and restrictions applied when browsing the merchant’s site (before the user gets to Global-e checkout), Bespoke needs to be able to read this information embedded within the DOM.
The respective “exceptions” data can be indicated in the data-countries data attribute for these products.
Below are 2 examples of how the “country exceptions” data attribute should appear on the website:
<div data-countries="{"IT" : {"restricted" : true, "vat" : 10.0}, "US" : {"restricted" : true}, "DE" : {"vat" : 7.0}}"></div>In the sample above, the product will be restricted in Italy and in the US and will have reduced VAT in Italy and Germany.
<div data-countries="{"all" : {"forbidden" : true}, "DE" : {"vat" : 7.0}}"></div>In the sample above, the product will be completely forbidden in all countries operated by Global-e and will have reduced VAT in Germany.
This information can be loaded by the merchant site’s back end from Global-e by periodically calling RecentProductCountryS API mentioned in the separate “Global-e API” document. Alternatively, the merchant may choose to render only commercial restrictions in the data-countries data attribute, in which case the default Bespoke behavior will still be preserved for the rest.
Product Classes Price Coefficients
For merchants wishing to apply a different price coefficient to specific product classes (eg. Premium items for certain territories), the respective product class code can be indicated in the data-pc data attribute for these products. The actual coefficient rate should be defined in the Global‑e system for the respective product classes in the required countries. The Bespoke script will take the specified product class into consideration, combined with the associated configuration (if a coefficient rate applies to the respective shipping country) when calculating the price for the customer.
Below is an example of how the product class data attribute should appear on the website:
<div data-pc="extra-charge">...</div>
The HTML attribute can be positioned on the DOM without country considerations as long as the Bespoke script establishes if the coefficient is applicable to the country.
In addition to setting the data-pc HTML attribute, product class code should be returned in
ProductClassCode attribute for the respective Product in GetCheckoutCartInfo API.
If needed, the applicable coefficients and associated countries can be recovered from Global‑e by calling the CountryCoefficients API mentioned in the separate “Global‑e API” document.
Excluding Elements from Price Conversion
By default, the Bespoke script converts all prices that are found on the page, to the selected end customer’s target currency, unless the certain element holding the price is explicitly excluded. The exclusion can be implemented either in the merchant-specific part of the Bespoke script as part of the integration scope on the Global‑e side, or by the merchant. For merchants wishing to exclude certain page elements from price conversion, the data-gem-ignore data attribute should be added to the respective HTML node.
For example, for a merchant having original prices in British Pounds, Bespoke will skip the following element and will not convert £100 to the target customer currency:
<div data-gem-ignore>Free Shipping for all orders over £100</div>
Manipulating Page Content
Merchants wishing to manipulate the page content based on the selected shipping country (for example to support promotional messages targeting), may use the data-manipulate data attribute.
The data-manipulate data attribute’s value should be JSON having HTML and/or CSS attributes for each country ISO code key that requires manipulation.
If specified, the HTML attribute should be set to any valid HTML that Bespoke will render as innerHTML of the respective node.
If specified, the CSS attribute should be set to any valid CSS that Bespoke will apply to the respective node.
In the example below, the “Free Shipping for all orders over €89” message will be shown only when the selected shipping country is The Netherlands:
<div data-manipulate= '{"NL" :{html":"Free Shipping for all orders over €89", "CSS":{"display":"block"}}}'></div>Showing or Hiding Page Elements
Merchants wishing to show or hide a page element only for Global‑e operated countries may use
globale-show or globale-hide CSS classes respectively.
For example:
The following DIV element will be hidden only when one of the Global‑e-operated countries is selected:
<div class = "globale-hide"></div>
The following DIV element will be shown only when one of the Global‑e-operated countries is selected:
<div class = "globale-show" style= "display: none;"></div>
Client Side Events
Global‑e Client SDK fires various client events that can be handled by the merchant. For example, OnBeforeWelcome event is fired just before Global‑e “welcome” popup is displayed and allows embedding merchant-defined dynamic content to Global‑e “welcome” popup.
For the list of all the available client-side events, please refer to Global‑e Client SDK documentation here: https://web.global-e.com/merchant/clientapi#eventssummary
Client Side Analytics
The Global‑e Module, along with the Global‑e Client SDK, allows Merchants to easily integrate any analytics framework,
e.g. Google Analytics. This is done by intercepting an event that the Global‑e checkout fires at the end of the checkout process (see Client-side events section above). Global‑e passes all order information to this event, allowing the merchant to take this information and push it to an analytics system of its choice. For more information, please refer to the Global‑e Client SDK documentation here:
Search Engine Optimizations (SEO)
For Merchants using Google Shopping Feed, Bespoke supports country-specific URLs that can be used in country-specific feeds. These URLs essentially instruct Bespoke to perform price conversions based on the query string parameter rather than by GEO-IP resolution by default. So, in a country-specific feed, the merchant may append glCountry=<country iso code> query string argument to all product URLs.
For example, in order to force the prices to be UK-specific, glCountry=GB should be appended to product URLs. Assuming the regular product page URL is https://www.merchant.com/product1.html , the UK-specific URL that may be used in the UK-specific feed would be https://www.merchant.com/product1.html?glCountry=GB. This will make all prices on the page nominated in GBP and localized for UK users.
For more information regarding SEO, please contact Global-e’s tech team.
Clearing the Cart
Global-e can ensure the cart is cleared after a successful international transaction.
Global-e can trigger a clear cart URL, delete a cookie or local storage value, or any combination of these operations to accomplish this. You will need to share what specific operations are necessary to clear the cart so that it can be configured on the Global-e side correctly.
However, if it is not possible to detach the frontend cart from the backend such that clearing the cart on the frontend will cause the SendOrderToMerchantprocess to fail, you will be required to clear the cart as part of the SendOrderToMerchant request.
If you do not rely on the information received from Global-e in the SendOrderToMerchant to create your orders, then clearing the cart on the front end should not result in the SendOrderToMerchant request failing, and the first option should be the preferred approach.