Headless - Global-e Docs

If you have a headless website, configure it as detailed in this section. Implement the following elements on your custom front end.

Localised Checkout

When building the checkout object, make sure to add the object’s relevant attributes to prevent the price and locale of the customer from falling back to domestic. It is important to pass the correct buyerIdentity otherwise the checkout experience of the merchant remains the default country and default currency of the website. See: https://shopify.dev/api/examples/international-pricing#create-a-checkout

Geo-Detection and Redirection - Headless Storefronts

You must implement geo-detection and redirection features using a custom or 3rd party solution that works with your headless storefront. The Marketing Banner shows the amount customers need to spend to get free shipping (in their own currency). For more information, please see Marketing Banner. The following procedure lets you load the shipping banner to the front end. This procedure assumes that you have the required technical knowledge to implement this solution. To add the marketing banner script to your website’s front end:

Create GLBE_PARAMS JavaScript variable on the site as follows:

GLBE_PARAMS = {  
                countryCode: "<country_code>", // 2 letter country code selected by the customer  
                currencyCode: "<currency_code>", // 3 letter currency code  
                isExternal: true
              }             

Example:

GLBE_PARAMS = {  countryCode: "CA",    currencyCode: "CAD",   isExternal: true} 

ONLY after GLBE_PARAMS variable is set, call Global-e script available as follows: Production

https://crossborder-integration.global-e.com/resources/js/app?shop=<myshopify_domain>

QA-INT

https://crossborder-integration-qa-int.bglobale.com/resources/js/app?shop=<myshopify_domain>

Positioning the Marketing Banner The Marketing Banner is inserted as the first element on your storefront. However, if this does not suit your store, Global-e can place the banner in a different location using the ID of an element. To insert the Marketing Banner in your preferred location on your storefront, add a new DIV element with a unique ID into your chosen location and share that ID with Global-e. This gives you complete control of the location of the banner and its position. Example

<div id=”GlobaleFreeShippingBannerContainer”></div>

Website Adjustments (Headless Storefronts)

Step 1. Price Conversion API

Shopify converts the price base. To set up international prices on your local headless website and build your catalogue, get the relevant prices in the relevant currencies: extract the prices by calling the productVariantByIdAndCountry API. Description: This API passes the country code variant Id and returns the relevant price. You can extract more than one variant in a call. See https://shopify.dev/api/examples/international-pricing#query-product-prices for more information. Query:

query productVariantByIdAndCountry($productVariantId: ID!, $countryCode: CountryCode!){
    productVariant(id: $productVariantId) {
        contextualPricing(context: { country: $countryCode }) {
            price { amount currencyCode }
        }
    }
}

Variable:

{
    "productVariantId": "gid://shopify/ProductVariant/000000000000",
    "countryCode": "GB"
}  

Example Return Body:

{
    "data": {
        "productVariant": {
            "contextualPricing": {
                "price": {
                    "amount": "16.0",
                    "currencyCode": "GBP"
                }
            }
        }
    }
}

Explicit Price Formatting To prevent shopper confusion and increase international order conversion, use explicit price formatting where appropriate, according to Shopify recommendations. This means displaying the currency code in addition to the currency symbol on collections pages, PDPs, search results, and order subtotals on the cart and mini-cart.

Step 2. Country Selector

If you have not done so yet, add a Country Selector to enable the customer to choose the preferred country. See https://shopify.dev/api/examples/international-pricing#query-product-prices and Step 3. Add a Country Selector. To get the list of all countries available for the selector, place a GraphQL API call (See https://shopify.dev/api/examples/international-pricing#query-available-countries-and-currencies).

Step 3. Gift Card Tagging

To prevent gift cards from receiving an inflated price due to country coefficients, you must add the product tag pc-glbe-giftcard to all your gift card products. Make sure to add this tag in both the sandbox and production environments. Please let your Global-e project team or CSM know when this is done so Global-e may complete the configuration on our side.

Step 4. Gifts With Purchase and Free Sample Support

To allow gifts with purchase and free samples to have international duties and taxes calculated correctly and prevent other downstream issues, there are two approaches:

The free products must be assigned a non-zero price and have a 100% discount applied to them.
Alternatively, the free product can have a price of zero ("0") if the configured “Cost per item” is non-zero. This method requires additional configuration from Global-e so please reach out to your Global-e project manager or CSM to enable it.

Additionally, for either method the free products must be present inside the cart to ensure that they are transferred to Global-e’s services. As an international merchant, protecting your customers’ privacy is essential. Shoppers in many countries prioritize their privacy, often looking for features like cookie banners as indicators of trust before engaging with a store or making purchases. Shopify offers robust tools to safeguard customer privacy and obtain consent before collecting analytical data. These tools are fully compatible with the Global-e Shopify Native solution, ensuring seamless integration. It is important to note that if cookie consent is not collected, Shopify does not provide you with analytical data for the shopper’s session. Therefore, proper configuration is essential for tracking your storefront analytics. To implement a custom cookie banner or use Shopify’s default banner for collecting analytical data from international customers, refer to the instructions in Shopify’s Customer Privacy API documentation. Additionally, Global-e can integrate with your cookie consent solution to ensure that Global-e cookies comply with your customers’ privacy choices. Reach out to your Global-e contact to discuss enabling this feature.

Email Notifications Adjustments

Include Duties in Your Email Templates

The following templates are located under Shopify Admin > Settings > Notifications.

Order Confirmation
Order Cancellation
Pending Payment Success
Order Refund

To include duties in your email templates, use the following code:

{% if current_total_duties or total_landed_cost_additional_fees %}
 {% assign total_duties_line = 0 %}
 {% if current_total_duties %}
   {% assign total_duties_line = total_duties_line | plus: current_total_duties %}
 {% endif %}
 {% if total_landed_cost_additional_fees %}
   {% assign total_duties_line = total_duties_line | plus: total_landed_cost_additional_fees %}
 {% endif %}
 <tr class="subtotal-line">
  <td class="subtotal-line__title">
   <p>
   <span>Duties</span>
   </p>
  </td>
  <td class="subtotal-line__value">
    <strong> {{ total_duties_line | money }} </strong>
  </td>
 </tr>
{% endif %}

To exclude the Taxes line when the amount is 0, adjust your template as shown below:

{% if tax_price > 0 %}
<tr class="subtotal-line">
  <td class="subtotal-line__title">
    <p>
      <span>Taxes</span>
    </p>
  </td>
  <td class="subtotal-line__value">
    <strong>{{ tax_price | money }}</strong>
  </td>
</tr>
{% endif %}

Customizable Products

If you sell customizable products (e.g., monogramming, etching, or embroidering names) for which you do not wish to accept returns, you can use a Global-e feature to indicate those products as non-returnable. To implement this feature:

Decide on a product tag to indicate a product is non-returnable. For example: nonreturnable or finalsale.
Tag your customizable products with your chosen tag by following the instructions here.
Inform Global-e of the tag you have chosen so that Global-e can configure the same tag in our system. Customers can now see your non-returnable tag when they view your items and they are prevented from returning the item after purchase.

Shopping / Marketing Feeds (Headless)

Domestic Feeds If you have implemented automatic Geo IP redirection on your storefront, you can update your domestic product links to include a country parameter to prevent Google feed violations. This requires that you add logic to your storefront to set the shopper’s session to match the country specified in the parameter and prevent Geo IP from firing. Example: {base_url}/{product_url}?country=US International Feeds If you plan to submit international product feeds, make sure to update your links to your products and your storefront logic so that when the shopper clicks the links, the country in the shopper’s session reflects the parameter or the country code embedded in the product path. Examples of product pages for Germany:

Storefront Attribute Script

The storefront attributes script is needed for Forter fraud and device detection features. To implement the storefront attributes script:

Add the following script tag to the head element of all storefront pages. Preferably, to the top of the HTML head section. Example for PROD.

<script async id="ge-storefront-js" data-mid="<GLOBALE_MERCHANT_IDENTIFIER>" 
 data-store="<GLOBALE_MERCHANT_STORE_IDENTIFIER>" data-env="prd" 
 src="https://web.global-e.com/Scripts/Merchants/globale.merchant.storefront.js"</script>

Example for QA:

<script async id="ge-storefront-js" data-mid="<GLOBALE_MERCHANT_IDENTIFIER>" 
 data-store="<GLOBALE_MERCHANT_STORE_IDENTIFIER>" data-env="int" 
 src="https://bglobale.com/Scripts/Merchants/globale.merchant.storefront.js"</script>

Use the following parameter values:

Parameter	Description
data-env	Global-e environment identifier. Can be one of the following values: “int” - Integration ”prd” - Production
data-mid	Encoded value of Global-e merchant ID. Note: You can get the encoded value from the mid-value in Global-e Admin, using Administrator credentials, from here: Admin > System > Encode/Decode > Encode Number.Global-e can provide this value in case of any issue with user permissions accessing the admin page.
data-store	The Global-e merchant store identifier for merchants with multiple production stores. Optional.
src	Environment URI. Can be one of the following: Integration: https://bglobale.com/Scripts/Merchants/globale.merchant.storefront.js Production: https://web.global-e.com/Scripts/Merchants/globale.merchant.storefront.js

Add listener to geCartAttributes event (sample code provided below). When geCartAttributes event is triggered, use Shopify Storefront API cartAttributesUpdate to update the Shopify cart with the same attributes provided by the geCartAttributes event. GeCartAttributes event data structure

{
 eventId:string,
  attributes:[
    {key:string, value:string}
  ]
}

Sample event

{
  "eventId": "23lkj4lk32j4"
  "attributes": [
    {
      "key": "key1",
      "value": "value"
    },
    {
      "key": "key2",
      "value": "value"
    }
  ]
}

Sample event handling code

document.addEventListener(
 "geCartAttributes",
 (event) => { 
// use event.detail.attributes to set Shopify cart attributes - i.e. with GraphQL storefront API
https://shopify.dev/docs/api/storefront/2023-07/mutations/cartAttributesUpdate
 },
 false,
);

Example The storefront attributes script provides the following attributes which need to be updated on the Shopify cart. This allows Forter to relate the checkout with your cart token, and based on the customer’s activity before the transaction, Forter’s fraud analysis is more accurate.

[
    {
        "key": "frtToken",
        "value": "9cc7e27f99084f52803d0369256c4342_1725451213641__UDF43_9ck__tt"
    },
    {
        "key": "isApplePay",
        "value": "false"
    },
    {
        "key": "cartToken",
        "value": "Z2NwLWV1cm9wZS13ZXN0MTowMUo2WUFSUkQxTjk0V0FXNjI5VE1ZQzkxWA"
    },
    {
        "key": "storeType",
        "value": "headless"
    }
]

Trigger the Global-e event geMerchantSession following any changes in event attribute values during the cart lifecycle, or on each page load. These event identifiers are used for Forter fraud detection and are shared with payment fraud service providers.

On Windows object, set the event message as global variable geMerchantSession. This ensures that Global-e can read the event in case geMerchantSession is fired before the Global-e script is loaded. geMerchantSession event data structure

{
  platformCartId: string, //shopify cart token
  cartId: string, //merchant managed cart id, can be same as Shopify cart token if no other card Id used by merchant
  sessionId:string //merchant managed customer session id
}

Sample event

{
  "platformCartId": "234kn234io23j4",
  "cartId": "jkh324kj5h324jk5",
  "sessionId":"nssdfg09usdf0gklm43"
}

Sample event handling code

window.geMerchantSession = {
  "platformCartId": "234kn234io23j4",
    "cartId": "jkh324kj5h324jk5",
  "sessionId":"nssdfg09usdf0gklm43"
}
document.dispatchEvent(new CustomEvent("geMerchantSession" , {
  bubbles: true,
  detail: window.geMerchantSession
});

​Localised Checkout

​Geo-Detection and Redirection - Headless Storefronts

​Marketing Banner

​Website Adjustments (Headless Storefronts)

​Step 1. Price Conversion API

​Step 2. Country Selector

​Step 3. Gift Card Tagging

​Step 4. Gifts With Purchase and Free Sample Support

​Step 5. Customer Privacy and Cookie Consent

​Email Notifications Adjustments

​Include Duties in Your Email Templates

​Customizable Products

​Shopping / Marketing Feeds (Headless)

​Storefront Attribute Script

Localised Checkout

Geo-Detection and Redirection - Headless Storefronts

Marketing Banner

Website Adjustments (Headless Storefronts)

Step 1. Price Conversion API

Step 2. Country Selector

Step 3. Gift Card Tagging

Step 4. Gifts With Purchase and Free Sample Support

Step 5. Customer Privacy and Cookie Consent

Email Notifications Adjustments

Include Duties in Your Email Templates

Customizable Products

Shopping / Marketing Feeds (Headless)

Storefront Attribute Script