> ## Documentation Index
> Fetch the complete documentation index at: https://nce-docs.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](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.

## Marketing Banner

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

1. 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} 
   ```
2. 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](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](https://polaris.shopify.com/foundations/formatting-localized-currency). 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](https://shopify.dev/api/examples/international-pricing#query-product-prices) and [Step 3. Add a Country Selector](/storefront-modifications-liquid-storefronts#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](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.

### Step 5. Customer Privacy and Cookie Consent

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](https://shopify.dev/docs/api/customer-privacy) 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:

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.](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/using-tags)
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](http://\{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:

* [https://merchant\_url/collections/products/t-shirt?country=DE](https://merchant_url/collections/products/t-shirt?country=DE)
* [https://merchant\_url/en-de/collections/products/t-shirt](https://merchant_url/en-de/collections/products/t-shirt)
* [https://merchant\_url/de/collections/products/t-shirt](https://merchant_url/en-de/collections/products/t-shirt)

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

   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:<br />"int" - Integration<br />"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:<br />Integration: [https://bglobale.com/Scripts/Merchants/globale.merchant.storefront.js](https://bglobale.com/Scripts/Merchants/globale.merchant.storefront.js)<br />Production: [https://web.global-e.com/Scripts/Merchants/globale.merchant.storefront.js](https://web.global-e.com/Scripts/Merchants/globale.merchant.storefront.js) |
2. Add listener to `geCartAttributes` event (sample code provided below). When `geCartAttributes` event is triggered, use [Shopify Storefront API](https://shopify.dev/docs/api/storefront/2024-07/mutations/cartAttributesUpdate) `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"
       }
   ]
   ```

   <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.
   </Note>
3. 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
   });
   ```