Skip to main content

Documentation Portal

Headless

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.

Free Shipping Banner

The Free Shipping 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 free shipping banner script to your website's front end:

  1. Create GLBE_PARAMS JavaScript variable on the site as follows:

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

    Example:

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

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

    Production

    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 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.

productVariantByIdAndCountry

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

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
Step 4. Gifts With Purchase and Free Sample Support
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:

  1. Decide on a product tag to indicate a product is non-returnable. For example: nonreturnable or finalsale.

  2. Tag your customizable products with your chosen tag by following the instructions here.

  3. 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:

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

    <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>

    Add the script to the following locations:

  2. When the cart is created or updated, trigger the Global-e event geCartAttributes with attributes taken from mutation.

    GetCartAttributes 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 adds the following to the 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": "frt_token",
	"value": "7c0476cf5c624f35bed149f7da569c12_1718049392570__UDF43_9ck__tt",
	"value_type": "string",
	"namespace": "globale"
}

    Note

    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.

  3. On window 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"
}
dispatchEvent(new CustomEvent("geMerchantSession" , {
  bubbles: true,
  detail: window.geMerchantSession
});