> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/ecom-platforms/shopify/global-e.md).

# Global-E x Shopify

## Overview

[Global-E](https://www.global-e.com/) is a cross-border e-commerce platform used by Shopify merchants to sell internationally. When a merchant enables Global-E (either through a direct integration or via Shopify's Managed Markets powered by Global-E), Global-E acts as the **Merchant of Record (MoR)** for international transactions. This means that international customers are legally purchasing from Global-E, not from the merchant, even though the transaction appears to happen on the merchant's storefront.

This document explains how Global-E's integration with Shopify works, why Violet cannot replicate this flow when creating orders via the Shopify API, and what this means for merchants who use both Violet and Global-E.

***

## How Global-E Works on a Shopify Storefront

### The Storefront Experience

When a Shopify merchant has Global-E enabled, international shoppers experience a modified version of the merchant's storefront. Global-E injects a client-side SDK (JavaScript) into the merchant's storefront that handles:

* **Country detection and switching:** Global-E identifies the shopper's location via IP geolocation and presents a welcome popup or country/currency switcher, allowing the shopper to browse in their local currency.
* **Price conversion:** Product prices displayed on the storefront (product listing pages, product detail pages, cart) are converted from the merchant's base currency to the shopper's local currency using Global-E's FX rates, country-specific pricing coefficients, and VAT adjustments.
* **Product restriction enforcement:** Products that cannot be shipped to the shopper's country (due to regulatory or commercial restrictions) are flagged or hidden.

Up to this point, the shopper is browsing the merchant's Shopify storefront normally. The Global-E SDK is modifying what they see (prices, currency, availability), but the underlying Shopify store is unchanged.

### The Checkout: Global-E's iFrame

The critical divergence happens at checkout. When an international shopper proceeds to check out, **they do not use Shopify's native checkout**. Instead:

1. The shopper's cart contents are transferred from the merchant's Shopify storefront to Global-E's servers via the `SendCartV2` API. This call includes all product details, prices, the destination country, and the selected currency.
2. Global-E's checkout is rendered inside an **iFrame** embedded in a container page on the merchant's site. The iFrame is hosted by Global-E and styled to match the merchant's branding, but it is entirely controlled by Global-E's infrastructure.
3. Inside this iFrame, Global-E calculates and displays:
   * **Localized product prices** in the shopper's currency
   * **Duties and taxes:** calculated by Global-E based on the product categories, HS codes, destination country regulations, and the merchant's configured duty/tax handling (DDP, DDU, inclusive pricing, etc.)
   * **International shipping options:** with costs and estimated delivery times from Global-E's carrier network
   * **The total landed cost:** the all-in price the shopper will pay, including product cost, shipping, duties, and taxes
4. **Payment is collected by Global-E**, not by the merchant. The shopper enters payment details into Global-E's checkout iFrame, and Global-E processes the transaction. The shopper is legally purchasing from Global-E.
5. Global-E performs a **fraud check** on the order. The merchant should not fulfill the order until this check is complete and the order status is updated to `PAID`.

### Order Creation: Global-E Writes to Shopify

After the shopper completes checkout in the iFrame, Global-E creates the order in Shopify on the merchant's behalf:

1. **Global-E calls the Shopify API** to create the order in the merchant's Shopify admin. The order is created using Shopify's multi-currency format with two currency representations:
   * **Presentment money:** the currency the international customer saw and paid in (e.g., EUR, GBP)
   * **Shop money:** the merchant's base store currency (e.g., USD), used for reporting and accounting
2. The Shopify order includes **Global-E-specific note attributes**, most importantly the `GEOrderId`, which links the Shopify order to Global-E's internal order record. This ID is required for all downstream Global-E operations (returns, refunds, financial reconciliation).
3. **Duties, taxes, and fees** appear as line items or note attributes on the Shopify order, depending on the merchant's configuration (e.g., whether duties are customer-paid, inclusive in price, or merchant-subsidized).
4. The order's initial payment status is `PENDING` while Global-E performs fraud review. Once cleared, Global-E updates the status to `PAID` via the Shopify API.
5. From an **accounting perspective**, the order should be treated as a domestic B2B transaction between the merchant and Global-E, not as a B2C transaction with the end customer. Global-E handles VAT/GST remittance, customs compliance, and financial settlement with the merchant.

### What Global-E Handles as Merchant of Record

When Global-E is the MoR for an international order, it is responsible for:

* **Collecting payment** from the international customer
* **VAT/GST registration, collection, and remittance** in each destination country
* **Duties and customs compliance:** including landed cost calculations and customs documentation
* **Currency risk:** settling with the merchant in their domestic currency regardless of what the customer paid
* **Fraud liability:** Global-E assumes fraud risk for orders processed through their checkout
* **Financial reconciliation:** providing the merchant with settlement reports

***

## Why Violet Cannot Recreate This Flow

Violet creates orders on behalf of merchants by calling the Shopify Admin API directly. This is fundamentally incompatible with Global-E's integration model for several reasons:

### 1. Global-E's Checkout Is Not an API

Global-E's duty/tax calculations, shipping options, and payment processing all happen inside their hosted checkout iFrame. There is no standalone API endpoint that accepts a list of products and a destination country and returns calculated duties and taxes. These calculations are tightly coupled to the checkout session and are not available outside of it.

### 2. Orders Must Originate from Global-E's Checkout for MoR Coverage

Global-E can only act as Merchant of Record for orders that flow through their checkout and payment infrastructure. An order created directly via the Shopify API, even if it's for an international customer in a Global-E-managed market, bypasses Global-E entirely. This means:

* **No duties or taxes are calculated** by Global-E for the order
* **No `GEOrderId`** is assigned, so the order is invisible to Global-E's systems
* **No MoR coverage:** the merchant, not Global-E, is the legal seller for that transaction
* **No VAT/GST remittance:** Global-E will not handle tax obligations for the order
* **No fraud coverage:** Global-E's fraud check does not apply
* **No financial reconciliation:** the order will not appear in Global-E's settlement reports

### 3. Global-E's API Does Not Support Standalone Duty Calculation

Global-E's API surface is designed to support their checkout-first model, not third-party order creation. While Global-E does offer APIs for shipping rates, price conversion, and product restriction checks, there is no endpoint to calculate duties and taxes independently. The duty/tax calculation engine is embedded in the checkout flow and is not exposed as a callable service.

### 4. Payment Cannot Be Retroactively Assigned to Global-E

Even if Violet could somehow calculate the correct duties and taxes, there is no mechanism to route payment through Global-E after the fact. Global-E's MoR status is established at the moment of payment. The customer must pay Global-E directly through their checkout. An order where the customer paid the merchant (or a channel) directly cannot be retroactively transferred to Global-E's MoR umbrella.

***

## Impact on Merchants Using Violet and Global-E

When a Shopify merchant uses both Violet and Global-E, the following applies:

### Domestic Orders (Non-Global-E Markets)

Orders created by Violet for **domestic customers** (e.g., a US customer buying from a US merchant) are **unaffected**. Global-E does not handle domestic transactions, and these orders flow through Shopify normally.

### International Orders in Global-E-Managed Markets

Orders created by Violet for **international customers in markets managed by Global-E** will bypass Global-E's checkout entirely. These orders:

* Will be created as standard Shopify orders with no Global-E involvement
* Will not include duty or tax calculations from Global-E
* Will not be covered under Global-E's MoR umbrella
* Will not appear in the merchant's Global-E financial reconciliation
* May create **tax compliance exposure** for the merchant, since VAT/GST obligations in the destination country are not being handled by Global-E

### Recommended Configuration

For merchants who require Global-E to be the Merchant of Record for all international orders, **international markets managed by Global-E should be disabled for orders originating through Violet**. This ensures that:

1. Violet only creates orders for markets where the merchant is prepared to handle tax and customs obligations directly (or where Global-E is not the MoR).
2. International customers in Global-E markets continue to purchase through the merchant's Shopify storefront, where Global-E's checkout iFrame handles the transaction correctly.
3. The merchant avoids unintentional tax compliance gaps from orders that bypass Global-E.

Merchants who are willing to process international orders without Global-E's MoR coverage, accepting responsibility for duties, taxes, and customs compliance themselves, may choose to keep international markets enabled for Violet. This decision should be made in consultation with the merchant's tax and legal advisors.

***

## Summary

| Scenario                                      | Violet Order Creation         | Global-E Involved?                | MoR Coverage                                         |
| --------------------------------------------- | ----------------------------- | --------------------------------- | ---------------------------------------------------- |
| Domestic order (e.g., US → US)                | Supported                     | No (not applicable)               | N/A                                                  |
| International order, non-Global-E market      | Supported                     | No                                | Merchant is responsible                              |
| International order, Global-E market          | Creates a Shopify order       | **No:** bypasses Global-E         | **None:** merchant assumes all tax/customs liability |
| International order via merchant's storefront | N/A (shopper uses storefront) | **Yes:** Global-E checkout iFrame | **Full:** Global-E is MoR                            |

Global-E's integration with Shopify is designed around a checkout-first model where international orders must originate from Global-E's hosted checkout to receive MoR coverage, duty/tax calculations, and financial reconciliation. Violet's order creation model, which calls the Shopify API directly, operates outside of this flow. Until Global-E provides API endpoints for standalone duty/tax calculation and third-party order ingestion with MoR coverage, these two systems cannot be combined for international orders in Global-E-managed markets.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.violet.io/ecom-platforms/shopify/global-e.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.