Storefront Attributes
The Global‑e integration relies internally on CSS selectors to locate various data points on your web store. This means that we may rely on a combination of:
The HTML structure of the page
Classes
Attributes (and their values)
Elements with specific IDs
To ensure a robust and seamless workflow, we highly recommend implementing the storefront attributes outlined in this document. By doing so, our team can configure our internal CSS Selectors to target these specific attributes. This empowers you to make future updates to your web store without needing assistance from Global-e to adjust the selectors.
Storefront attributes not only streamline our integration process but also significantly enhance the stability and efficiency of your integration.
Country Switcher Flag
The Country Switcher flag (data-ge-shippingswitcher-flag) lets you position your country switcher on your storefront.
Insert an element.
Assign the corresponding attribute at the location you want the Country Switcher to be displayed on your storefront.
Our design team can work with you to style the country switcher to match your brand, so please reach out if you have any specific requirements.
Example
<nav class="header"> <img src="logo.png"> <a href="/home”>Home</a> <a href="/collections/all">Shop</a> <span data-ge-shippingswitcher-flag /> <span>My Cart</span> </nav>
For placement on desktop browsers: [data-ge-shippingswitcher-flag]
For placement on mobile browsers: [data-ge-mobile-shippingswitcher-flag]
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>
General Price
Place the Price flag (data-ge-price) on any price element on the product details page and product list pages (search results, categories, and more). This does not need to be applied if another price attribute is also applied.
Do not apply this attribute to Basket or Mini Basket prices. See the Basket / Mini Basket section for the attributes to apply to these prices.
Example
<div data-ge-price>$19.95</div>
Custom Price Calculation
These attributes are meant to be combined in order to accurately calculate more complex prices outside of the cart, for example, when advertising prices in a Product’s description.
Base Price - [data-bp="{BasePrice}"]
This attribute specifies the {BasePrice} (or price-per-unit) to be used when doing price calculations.
Quantity - [data-quantity="{Quantity}"]
This attribute specified the {Quantity} (or number of units) to be used when doing price calculations. If no quantity is specified (or the attribute is omitted), then the default value of 1 will be assumed.
Example
<div> Normally <span data-ge-price>$10</span>, Buy 10 at <span data-bp="5">$5</span> each, Totaling <span data-bp="5" data-quantity="10">$50</span> </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 GEM behaviour will still be preserved for the rest.
Reduced VAT Rate
For merchants that have reduced VAT rate products in the catalogue
(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 takes the specified VAT rate into consideration when calculating the price for the customer.
The following example shows how the VAT rate data attribute should appear on the website:
<div data-product-vat="0"...</div>
<div data-product-vat="20">...</div>
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
The ProductClass 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>
Basket / Mini Basket
Here are the most common basket selectors. We have many more, but these are the most common. Let us know if any price in the basket is not covered, including discounts, subtotals, product savings… anything at all… and we will look up the appropriate attribute for you.
Name | Attribute | Explanation | Example |
|---|---|---|---|
Add to Cart Button |
| Place this attribute on any button on PDP that adds the item to the cart. This attribute can also be applied to any clickable element ( | |
Basket SubTotal |
| Total List Price for the Basket/Mini Basket. | |
Basket Total |
| Total Sale Price for the Basket/Mini Basket. | |
Basket Total Discount |
| Total Discounts for the Basket/Mini Baskets (Basket | <table> <tbody> <tr data-ge-basket-cartitemid="SHOE_2024"> <td>Future Shoe</td> <td>x5</td> <td data-ge-basket-productsaleprice> $10 </td> </tr> <tr data-ge-basket-cartitemid="LKYHAT843"> <td>Lucky Sports Hat</td> <td>x1</td> <td data-ge-basket-productsaleprice> $50 </td> </tr> </tbody> <tfoot> <tr><td> <span>Total: </span> <span data-ge-basket-totals>$100</span> </td></tr> </tfoot> </table> |
Product CartItemId |
| Place this on the product "row" in the Basket/Mini Basket. The { | |
Product ListPrice |
| The original list price of the product. | |
Product SalePrice |
| The discounted sale price of the product. | |
Product SubTotal |
| The total list price of the product (List Price * Quantity). | |
Product Total |
| The total sale price of the product (Sale Price * Quantity). | |
Product Total Discount |
| The total discount for this product (Total List Price - Total Sale Price). |
Checkout
Checkout Button - [data-ge-checkout-button]
Place this attribute on any button that takes you to checkout. This can be applied to any clickable element (a, input, div, span, etc…), not just buttons.
Checkout Container - [data-ge-checkout]
Place an element with this attribute where you would like our checkout to be injected on the /pages/international-checkout page.
Element Visibility
These attributes will hide & show elements when the customer is in a Global-e operated country.
The two attributes can be used together to show one piece of information for domestic customers and a different piece of information for international customers.
It is best to keep “Global‑e operated” in mind when thinking about if something should be hidden or shown.
Hide - [data-ge-hide]
This attribute sets the property display: none !important; (via CSS) when the customer is in a Global-e-operated country and does nothing when in a non-operated country.
This has the effect of hiding the element for international customers while keeping that element visible for non-operated customers.
Show - [data-ge-show]
This attribute sets the property display: block !important; (via CSS) when the customer is in a Global-e-operated country, and sets it to display: none; when in a non-operated country.
This has the effect of showing the element for international customers while keeping that element hidden for non-operated customers.
This is only to be applied to elements you wish to be shown exclusively to international customers but remain hidden for domestic customers.
Example
This example shows how one message can be shown for domestic customers, while a different message is shown for international customers.
<div data-ge-hide> Free Shipping! </div> <div data-ge-show> Shipping is calculated at checkout. </div>