Skip to main content

Documentation Portal

Orders Processing

This document is relevant for any system such as an OMS/ERP, WMS, or middleware that is importing Global-e orders from Shopify.

Key Shopify order data is illustrated as well as high-level downstream order flow for mapping purposes. If you are currently running live Global-e’s previous Shopify integration and upgrading to the new version integrated natively into Shopify’s checkout, you will find additional information in Migrating Global-e to Native App.

Downstream Data Flow from Shopify

At Checkout, Global-e begins calculating the international prices, duties & taxes, and shipping methods.

Orders are created by Shopify and per Shopify’s multi-currency concepts, in two currencies:

  • Presentment money: what international customers see on the storefront, cart, checkout, and transactional emails.

  • Shop money: The main currency of your Shopify store and the currency used for reporting and analytics.

    Note

    Shop money is what should be mapped downstream by your order management and accounting systems.

Downstream_Data_Flow_from_Shopify.png

Fraud check

Global-e performs a fraud check for international orders.

  1. Initial order creation has the payment status PENDING (financial_status property).

    Important: Merchants should not submit any orders for fulfilment at this time and wait on Global-e to complete the fraud check.

  2. When the fraud check is completed, the payment status is updated to PAID. Orders may now be submitted for fulfilment.

WMS and operations

For Global-e to generate international shipping labels & customs documents, the warehouse pick-pack process must reference Shopify’s order name and SKU.

Alternatively, the Shopify order number and/or Shopify EAN/barcode/variant ID may be used instead.

Reach out to Global-e as additional configuration may be needed in those cases.

End-to-End Order Flow Interfaces

A general illustration of an order flow with Shopify to OMS to WMS and Global-e in the picture.

end_to_end_order_flow_interfaces.png

Outbound

  • Order creation: created in Shopify with initial payment status 'PENDING’ and order tag ‘Globale::Pending’.

  • Fraud check: upon successful fraud check (asynchronous process), the payment status goes to ‘PAID’ and the order tag is replaced with ‘Globale::Approved’.

  • Export to OMS/WMS qualified orders: with ‘PAID’ status or tagged with Globale::Approved.

  • Pick and pack: used by the warehouse to identify orders via the Shopify order name/number and sku/upc.

  • Label generation: Global-e interface provides a final mile carrier label and a tracking number.

  • End-of-day manifest: signals to Global-e that the order is ready to be dispatched and generates an end-of-day document.

  • Fulfilment update to Shopify: in most scenarios, this event or the tracking number itself is provided by Globale. It is also expected for Shopify to send the shipment confirmation email when its fulfilment is created.

Shopify Order Data Examples

This Shopify store belongs to a US merchant and the storefront currency is in USD.

Below are two different order scenarios in which a single product is purchased:

  • Duties & taxes are paid by the customer – the checkout explicitly displays D&T-related line items.

  • Duties & taxes are inclusive/baked into product prices – the merchant subsidizes the D&T costs.

Scenario 1: Duties & taxes paid by the customer

Market: Israel.

The customer pays separately for all the D&T-related costs including the customs clearance fee (CCF) represented here in the “Additional Fee” field.

additional_fee_field.png

Note

The Additional Details section is for information and is not required for data consumption. CalculatedDutySubsidy represents the total order level subsidy in storefront currency. In this example, there is no subsidy for this order, hence the $0.

paid_example.png

Important

The Additional Fee set is a new Shopify data line available in Shopify’s API release version 2023-04. See https://shopify.dev/docs/api/admin-rest/2023-04/resources/order for reference.

Scenario 2: Duties & taxes are included in the product price

Market: United Kingdom.

Duties, taxes, and customs clearance fees are all-inclusive in the £500.00 product price in this example.

duties_and_taxes_for_uk__market.png

CalculatedDutySubsidy 139.72 USD includes duties, VAT, and CCF.

Note: the D&T line items do not appear in the order details at all.

paid_uk_market.png

Conclusion

  • Duty, tax, and customs clearance fees (CCF) are all part of the overall duties and taxes calculation.

  • When a customer’s checkout displays duty & tax-related fees, these costs appear as order line items.

  • Any subsidized costs, whether both duties and taxes or just duty or just taxes – appear in the note attributes CalculatedDutySubsidy field.

Accounting Perspective

From a Shopify view, orders are created per customer as a B2C transaction with Global-e. From an accounting perspective, orders should be treated as domestic B2B orders booked against a Global-e account.

You may book any order line items to calculate gross revenue while bearing in mind that in most scenarios Global-e is responsible for handling remittance and filing local VAT and other taxes.

For estimated net revenue, you can subtract the CalculatedDutySubsidy field. For actual revenue, refer to the Global-e financial reconciliation report.

Shipping Lines

When the Global-e CrossBorder app is installed in Shopify, a shipping zone with Global-e operated countries is automatically added. The order shipping lines data is standardized by Shopify and cannot be changed.

"shipping_lines": [{
 "id": 4525092405308,
 "code": "EXPRESS_GLOBALE_DDP",
 "source": "Global-e Carrier Service",
 "title": "Express Courier (Air)"

See below for the list of possible values for the relevant fields.

  • Source: fixed value Global-e Carrier Service.

  • Title: two possible values, Express Courier (Air) or Standard Courier.

  • Code: multiple permutations depending on service type. Will always contain ‘GLOBALE’.

shipping_lines.png
Shopping / Marketing Feeds

You can leverage Shopify’s sub-folder structure and the geolocation app to build international product feeds.

Examples

Shopify Markets API for product price retrieval

Migrating Global-e to Native App

If you are presently running live on the legacy version of Global-e’s Shopify integration, a.k.a the “hosted checkout”, you must migrate to the latest version where Global-e is natively integrated into Shopify’s checkout.

These are the key changes to Shopify order data:

  • Order transaction is no longer per B2B transaction in a single currency, but per customer B2C transaction instead with presentment currency and shop currency. The B2B VAT is no longer reflected in Shopify.

  • Order id – Shopify order_name no longer starts with ‘GE’ (e.g, GE2034304US). Orders name is now assigned by Shopify same as for domestic orders (eg., #1234). The Global-e order id is available, see below “From the “Additional Details” section in order data”

  • Shipping lines/code is now standardized by Shopify as explained in the previous section.

  • Shipment confirmation emails no longer come from Global-e but instead are managed by Shopify/merchant.

  • Fraud approval no changes to this flow, still relying on the payment status “pending” (before fraud check) and a subsequent update to “paid” status upon fraud approval with the addition of an order tag “Globale::Approved”

  • Payment gateway no longer shows ‘globale’, instead:

    • Global-e Payment (INT) when installing the Global-e payment method in production mode.

    • Global-e Payments when installing the Global-e payment method in test mode.

From the “Additional Details” section in order data

The Global-e order is still available in Shopify, however not upon initial order creation and only as a note_attribute, which is updated by the Global-e Shopify app a few seconds post-order creation.

Example

"order": {
 "id": 4525092405308,
 "name": "#1976",
 "note_attributes": [
 {
 "name": "GEOrderId",
 "value": "GE10071428326US"
 }
Shopify Order JSON example

A full example of an order JSON file can be downloaded here:Shopify Order JSON example.