Skip to main content

Documentation Portal

Returns Provider Integration Guide

Introduction

This guide is designed for Returns solution providers operating on Shopify who wish to integrate with Global-e’s returns, refunds and exchange flows for Global-e operated orders.

  • Audience: Product & Engineering teams at return solution providers, integrating with Global-e over Shopify.

  • Purpose: Enable seamless connectivity to Global-e’s comprehensive suite of operations for managing returns, exchanges and refunds.

Why integrate:

  • Expand market reach by connecting with Global-e’s global network of Shopify merchants.

  • Drive adoption by enabling localized, seamless and consistent returns and exchanges experience cross domestic and cross border transactions.

  • Add strategic value with support for complex cross-border return flows and stronger merchant partnerships.

Roles and Responsibilities

Merchant

  • Defines merchant policies in the Return Provider’s admin (product/order eligibility, return reasons, return windows, refund rules).

  • Defines shipping options and flat shipping costs in Global-e admin.

  • Reviews and approves RMAs and refunds when set to manual approval.

Return Provider

  • Serves as the shopper-facing portal for initiating returns/exchanges.

  • Fetches order data from Shopify and verifies whether Global-e operates the order.

  • Manages merchant return/exchange policies and RMA logic.

  • Communicates with Global-e the “Provider Name” identifier which will be sent on the API calls.

  • Obtains the merchant’s GUID from the merchant, for each merchant they wish to onboard.

  • Calls Global-e APIs to:

    • Get return shipping options (Carrier, service, PrePaid return cost)

    • Get return documents (label, invoice, shipping instructions, tracking number)

    • Get tracking events (for notification and refund automation)

  • Delivers RMA documents, shipping labels, and instructions to the shopper.

  • Creates exchange orders on Shopify when applicable.

  • Supports refund automation based on tracking events (e.g., auto-refunds).

Global-e

  • Acts as Merchant of Record for Global-e-operated orders.

    • Assumes full liability for cross-border compliance

    • Owns or manages logistics flows

    • Issues shopper refunds

  • Provides and manages:

    • Return addresses, carrier restrictions, and cross-border compliance.

    • Shipping options, prepaid labels, and shipping instructions.

    • Tracking events.

Shopify

  • Acts as the central commerce platform linking Merchant, Global-e, and Return Provider.

  • Stores and exposes order data for Return Provider validation.

  • Handles stock reservations and order creation for exchange flows.

Before You Start

API Referenced in this Document

High-Level Flows
Return Flow
Image_1_-_Return_Flow.png

  1. Shopper initiates return

    1. Shopper initiates a return in the returns provider’s portal, usually by entering an Order ID and Email.

    2. The return provider fetches order details from Shopify and validates whether the order is Global-e operated.

    3. Global-e order can be recognized by the following attributes:

      • "merchant_of_record_app_id": 5806573

        Note

        For testing environment use “merchant_of_record_app_id": 5806443)

      • If you do not have the "merchant_of_record_app_id" attribute, you can fallback to using Global-e OrderID. Each OrderId, string, has prefix GE followed by numbers, in the format GE1234.

    4. The merchant_of_record_app_id": 5806573 attribute is used to recognize the Global-e order.

      Example:

      "note_attributes": [
  {
    "name": "GEOrderId",
    "value": "GE137255874US"
  }
]

  2. Shopper chooses item(s) to return

    1. Product return eligibility is managed by:

      1. Returns provider: order, product, and RMA eligibility rules.

      2. Global-e: carrier and cross-border regulation restrictions (e.g., dangerous goods, import limitations, product restrictions per shipping method).

      Note

      • Global-e validations occur during the GetReturnShippingOptions API call and may disqualify the return.

      • The return provider fetches product prices from Shopify in the presentment currency and displays them in their portal to the shopper in this form.

      • Multiple RMA requests are supported per order for different products, but customers cannot create multiple RMAs for the same product.

  3. Shopper provides return reasons:

    1. Return reasons are managed by the return provider

    2. Shopper selects item(s) to return and provides reasons in the return provider’s portal.

    3. Return provider to send return reason description to Global-e via the GetReturnDocuments API later in the flow.

    Note

    • Global-e does not support multiple return reasons for items with the same SKU. If a customer returns several units of the same SKU (for example, three t-shirts of the same model), only one return reason applies to the entire group. Assigning different return reasons to individual items within the same SKU is unsupported.

    • Multiple items with the same SKU, must be sent as one object in the ReturnedProducts array, with ReturnQuantity > 1.

    • When calling GetReturnDocuments API make sure to NOT send the return reason code, just the return reason description.

    • If you manage return reasons hierarchically, note that Global-e accepts only one return reason description per item.

  4. Shopper selects Return Method

    1. The return address is managed and stored by Global-e.

    2. Call Global-e’s GetReturnShippingOptions API to get available shipping carriers, services, and rates.

      1. API authentication is done via Merchant GUID- a unique key provided to the Merchant, by Global-e. The Merchant GUID key should be passed in the API header.

      2. In order to obtain the Merchant GUID please contact your Merchant

      3. Obtain Unique Global-e Order ID: Note: each OrderId, string, has prefix GE followed by numbers, in the format GE1234.

      4. Mandatory request fields:

        Field

        Description

        OrderId (string)

        Unique Global-e Order ID.

        Maximum: 100 characters.

        ProviderCode (string)

        Provider name or initials that identifies the source of the request.

        Examples:

        Loop, Redo, ParcelLab.

        CurrencyCode (string)

        CurrencyCode should be passed as per Shopify order.presentment_currency code on the order.

        ReturnedProducts (Array of Products)

        The following fields should be populated:

        • CartItemID → corresponds to Shopify field LineItemId

        • ReturnQuantity

    3. Shopper views available shipping options with corresponding rates and selects one.

      Note

      • Shipping options and prepaid shipping rates are managed by Global-e.

      • Global-e returns multiple shipping options as configured by the merchant (e.g., express, standard, self-postage).

      • If the return provider supports only one shipping method, they must inform the merchant and ensure the correct return method is selected for each shipping lane.

      • Carrier restrictions are managed and validated by Global-e (e.g., dangerous goods, import limitations, product restrictions per shipping method).

      • Returns can only be done from the country where the order was initially delivered.

  5. Shopper indicates refund method

    1. Refund can be issued as:

      1. Original payment method - initiated by the returns provider and issued by Global-e

      2. Shopify Gift Card - managed by the returns provider

    2. More information on refunds is available in the refund flow section below.

  6. Shopper confirms return

    1. Call Global-e’s GetReturnDocuments API to initiate an RMA and get return documents.

      1. Mandatory fields:

        Field

        Description

        OrderId (string)

        Unique Global-e Order ID or Merchant Order ID.

        Maximum: 100 characters.

        ProviderCode (string)

        Provider name or initials that identifies the source of the request.

        Examples:

        Loop, Redo, ParcelLab

        ReturnedProducts (Array of ReturnedProduct)

        An array containing the returned products' details.

        • MerchantReturnReasonDescription

        • CartItemID - corresponds to Shopify field LineItemId

        • ReturnQuantity

      2. The API shall return the following:

        • Global-e RMA number

        • Return shipping label

        • Shipping instructions

        • Commercial Invoice - Optional

        • Tracking Details - an array which includes the TrackingNumber - this number should be saved in order to later use the GetTrackingEvents API.

    2. The return provider creates the return in Shopify, including the ReturnShippingFee, and provides the return label and instructions to the shopper.

      • Shopper is sent a return confirmation with the return documents.

      Note

      When migrating from Global-e’s returns solution to a 3rd party returns provider, it’s important to note that Global-e can manage all returns-related customer emails (such as RMA notifications). If the third-party provider will handle these communications instead, the email notifications on Global-e’s side must be disabled to prevent duplicate messages.

  7. Get label and ship product back

    1. Shopper downloads label and instructions.

    2. Shopper sends parcel.

    3. Optional: Global-e provides a tracking events API for its carriers:

      1. call GetTrackingEvents API for tracking updates.

Refund Flow

This section defines how refunds are initiated, communicated, and processed between the Return Provider, Global-e, and Shopify after a refund is approved.

Refund Initiation

Although the refund is initiated in Shopify, the actual payment to the shopper is done by Global-e. In order to make sure that we won’t have double refunds or incorrect refunds, it is very important to follow the guidelines below which defines the proper way to initiate the refund via Shopify.

Handling Return Shipping Fees

  1. When creating a refund in Shopify, the return provider, should specify what is the deducted shipping fee for the return by declaring the prepaid amount in presentment_currency in the Shopify Native ReturnShippingFee return property.

  2. Shipping fees are managed by Global-e and available via the GetReturnShippingOptions API.

  3. Shopify will deduct the shipping cost from the refund amount, Global-e will get this information from Shopify and will refund the shopper with the correct amount.

  4. If the return provider does not specify the shipping fee, GE will refund the shopper with the full amount which was sent from Shopify and will charge the shipping fee from merchant.

    Image_2_-_Refund_Flow.png

  5. Refund logic:

    • The Return Provider must create a return and specify the return shipping fee.

    • The Return Provider needs to refund the return and call the Shopify API: returnRefund to connect the refund to the return.

Refund Execution

  • Global-e receives the refund request from Shopify (via webhook).

  • Global-e checks if the refund amount includes the return shipping fee deduction.

  • The relevant amount is refunded to the shopper by Global-e and details are logged.

  • Shopify’s declared return shipping fee determines what the shopper pays.

    Global-e’s shipping flat fee represents the agreed-upon amount that must always be fully accounted for, either by the shopper, the merchant, or a combination of both.

  • During reconciliation, Global-e ensures the flat fee is fully covered:

    • If Shopify undercharges (Return provider declares a lower fee), the merchant is fully responsible for covering the remaining balance between Shopify’s declared fee and the Global-e shipping flat fee.

    • If Shopify overcharges (Return provider declares a higher fee), the merchant receives the difference between the higher shopper charge and the Global-e shipping flat fee.

In other words, the merchant remains fully responsible for any financial difference between Shopify’s declared return shipping fee and the Global-e shipping flat fee they configured.

Reconciliation and Reporting

  1. Details about refund, items, and shipping fees are included in finance/merchant reconciliation.

  2. Refund status and data is synchronized between Shopify and Global-e for full order lifecycle tracking.

    Important

    • The Return Provider should include all adjustments (shipping, duties, etc.) in the corresponding fields in Shopify.

    • The net refund amount sent to Global-e from Shopify must reflect any deductions or additional charges.

    • Global-e will handle financial reconciliation with the merchant for these adjustments.

Alternative Refund Methods

If the shopper selects a Shopify Gift Card instead of an original payment refund:

  • The refund is processed entirely within Shopify by the Return Provider.

  • The Return Provider should record the transaction internally and update the RMA status to "Refunded (Gift Card)".

    Important

    • Global-e does not support currently “Shopify Store Credit”. Shopper will not be able to use this type of payment.

    • When a refund is made to a Gift Card, Global-e cannot see that transaction. To avoid double refunds, ensure that no “Auto Refund” automation is enabled on Global-e side.

Refund Automation and Tracking

  • Refund automation enables seamless refund initiation based on parcel tracking events or internal system rules.

  • Automation can be owned by either by Global-e or by the return provider.

  • The Return Provider can monitor tracking statuses via the GetTrackingEvents API to trigger the refund programmatically.

    Automation Ownership

    There are two possible automation configurations:

    1. Refund automation managed by Global-e

      • Refunds are triggered automatically once the tracking event matches the configured rule (e.g., in transit or delivered).

      • The Return Provider should not issue a separate refund to avoid duplication.

    2. Refund automation managed by the Return Provider

      • Refunds are triggered within the provider’s system.

      • In this case, Global-e’s automation must be turned off to prevent double refunds.

      • To disable automation on Global-e’s side, the merchant must submit a support ticket to Global-e.

    Tracking Events API

    • The Return Provider can monitor parcel progress via the GetTrackingEvents API.

    • The TrackingNumber is received as part of the response of the GetReturnDocuments API and should be saved by the return provider in order to be used in calling the GetTrackingEvents API.

    Parameter Name

    Type

    Description

    Mandatory

    OrderIds

    List of Strings

    List of Global‑e Order IDs. Up to 100 in each request.

    Max length:100 chars.

    One of either OrderIds or TrackingNumbers is mandatory.

    TrackingNumbers

    List of Strings

    List of Global-e tracking numbers. Up to 100 in each request.

    Conditional

    Type

    String

    The shipment direction: inbound

    Yes

    • Supported tracking states include in transit, delivered, returned to sender, etc.

    • Merchants can configure automated refund triggers based on these statuses.

    Double Refund Prevention

    If both Global-e and the Return Provider (or the merchant directly in Shopify) trigger refunds, a double refund may occur.

    To prevent this:

    • Refund automation should exist only on one side (Global-e or Return Provider).

    • Coordination between Global-e, the Return Provider, and the merchant is required before enabling automated refunds.

    Notifications and Emails

    Refund and RMA-related email notifications can be sent either by Global-e or by the Return Provider, depending on merchant preference.

    Global-e Notifications

    • Global-e can automatically send RMA confirmation emails to shoppers.

    • If the merchant prefers Global-e to send these, no additional configuration is required.

    Return Provider Notifications

    • If the Return Provider manages customer communication, to avoid duplicate notifications, Global-e’s email notifications must be disabled.

    Disabling Global-e Notifications

    To disable email notifications on Global-e’s side:

    1. The merchant (or partner) must open a support ticket with Global-e.

    2. Specify which notifications should be disabled (refund configuration, RMA confirmation, etc).

    3. Global-e will update the merchant configuration accordingly.

Even Exchanges

Supported Exchange Scenario

Global-e supports even exchanges (Variant-exchange) only:

  • No refunds or additional charges are allowed.

  • Shipping fees cannot be collected or refunded.

  • All shipping costs and any duty/tax adjustments are absorbed by the merchant as part of the service.

Exchange Flow

Image_3_-_Exchange_Flow.png

  1. Shopper initiates an exchange

    1. Shopper enters order details in the return provider’s portal.

    2. After fetching order details from Shopify, the return provider validates whether the order is Global-e operated.

      • "merchant_of_record_app_id": 5806573

        Note

        For testing environment use “merchant_of_record_app_id": 5806443)

      • If you do not have the "merchant_of_record_app_id" attribute, you can fallback to using Global-e OrderID. Each OrderId, string, has prefix GE followed by numbers, in the format GE1234.

  2. Shopper selects items to be replaced

    • Shopper selects the items to be replaced and provides return reasons in the return provider’s portal.

  3. Return shipping options

    • The return provider calls GetReturnShippingOptions API to fetch available shipping options (free shipping / self postage only).

    • Shopper selects the return method.

    • The return provider provides the return label and shipping documents.

      Note

      For prepaid shipping rates, the shopper will not be charged for return shipping; it will be settled by the merchant as part of the Global-e merchant reconciliation process.

  4. Shopper selects replacement items

    • The return provider queries Shopify to fetch the available replacement variants (ensuring stock availability).

    • The return provider displays the eligible replacement catalog to the shopper.

    • Shopper selects the desired replacement item/variant.

    • The shipping option for the exchange order will be assigned by Global-e based on the merchant’s preference.

      Note

      The shopper will not be charged this rate; it will be settled by the merchant as part of the Global-e merchant reconciliation process.

  5. Shopper confirm exchange

    • Shopper confirms the exchange in the return provider’s portal.

    • The return provider calls GetReturnsDocument API to fetch the return shipping documents.

    • The return provider creates the RMA and provides the return label and instructions to the shopper.

    • Shopper is sent an exchange confirmation with the return documents (this notification can also be triggered directly by Global-e and is configurable).

  6. Draft Exchange Order creation in Shopify

    • The return provider creates an exchange draft order in Shopify and reserves stock if applicable.

    • Shopify exchange order recognition by Global-e:

      • Order must not have "ReplacementForOrder" note. This field will be filled by Global-e after creating the replacement order.

      • The order must include OriginalShopifyOrderId in note_attributes:

        "note_attributes": [
  {
    "name": "OriginalShopifyOrderId",
    "value": "123456789"
  }
]

  7. RMA approval

    • RMA approval logic for exchange orders is managed by the return provider.

    • On the return provider’s side, RMA can be approved manually (the merchant reviews and approves), or automatically in specified cases (e.g., low-value returns), or using tracking event logic.

    • Global-e offers a tracking events API for its carriers to support tracking-events-based RMA approval.

    • Once the RMA is approved, the draft exchange order needs to be converted to a regular Shopify order by the return provider.

  8. Exchange order processing

    • The Shopify exchange order is recognized and processed as a Global-e replacement order.

    • Once the Global-e replacement order is created, Global-e updates the ReplacementForOrder field on the replacement order.

    • Replacement order is fulfilled and shipped using the recommended shipping logic.

      Important

      • Before integrating, contact your Global-e representative to ensure the merchant is properly configured in Global-e Admin.

      • Shipping recommendations

        • Incoming (return): for exchanges ONLY free shipping / self-postage options should be available.

        • Outgoing (replacement): The merchant can reuse original shipping line or use the standard shipping method.

      • Merchant responsibility

        • Return providers must inform merchants that Global-e supports only even-value exchanges with free shipping, with any shipping or duty/tax costs covered by the merchant.