Subscriptions Overview

For the integration itself, see the Subscription Connector (End-to-End) — the API endpoints, request flows, authentication, and idempotency.

​

Introduction

The Global-e Subscription Connector enables merchants to sell subscription products with Global-e as the Merchant of Record (MOR). It bridges the merchant’s subscription manager with Global-e’s checkout, payment, and compliance capabilities, allowing seamless recurring billing for digital, physical and hybrid goods - with full localization, shipping, and tax and duty management. Using the Subscription Connector, merchants can offer recurring purchases to shoppers globally, while maintaining the same localized checkout experience they already use for one-time orders. Key Benefits:

• Seamless integration with third-party subscription managers
• Support for recurring payments (including trials and discounts)
• Full localization of pricing, shipping options, taxes, and duties
• Secure tokenization and PCI-compliant storage
• Automated fraud checks aligned with Global-e’s payment risk controls
• Simplified compliance and reporting under Global-e’s MOR model
• Support for digital, physical, and hybrid (physical + digital) subscriptions, including shipping, physical order documents, and hub-based fulfilment

​

Integration Roles and Responsibilities

To ensure a successful integration, it’s important to understand the division of ownership between the Merchant, Subscription Manager, and Global-e. Summary:

• The Subscription Manager is the system of record for subscription lifecycle management.
• Global-e handles all payment, fraud and compliance-related functions.
• The Merchant oversees storefront setup, communication, and operational coordination.

​

Core Capabilities

The Global-e Subscription Connector combines Global-e’s cross-border commerce expertise with third-party subscription management tools to enable recurring payments, shipping, compliance, and localization at scale.

​

Payments & Tokenization

• Shopper payment details are securely collected during the initial checkout and tokenized for future recurring charges (MIT – Merchant Initiated Transactions).
• Tokenization is handled entirely by Global-e’s PCI-compliant systems or, in the case of PayPal, via a vaulted payment reference.
• Fraud screening is performed on every payment, including recurring transactions, with manual review for any challenged cases.
• Subscribers can change the payment method on an active subscription: Global-e provides an API for the merchant to display the current method and a secure update widget. Credit cards and PayPal are supported, including switching between them.

​

Localization, Tax & Duties

• The checkout flow is fully localized for currency, language, and tax display - identical to the regular Global-e experience.
• All duties and taxes are calculated and collected according to Global-e’s configuration. Supported duty policies: Hidden Force DDP and Partial Force DDP; for physical-only subscriptions, also Force DDP and DDU are supported.
• Global-e remains the Merchant of Record (MOR) for all subscription transactions, handling compliance, remittance, and reporting.
• Global-e exposes a “Billing Summary calculation” API for recurring billing: before each renewal it recalculates shipping, tax, and duties against current pricing, shipping options, and regulations. The Subscription Manager uses it when creating renewal invoice.
• For subscriptions, tax exemption is re-evaluated on every recurring order from the shopper’s registered email address, so it applies only while the exemption is still valid.

​

Shipping & Fulfilment

• For physical/hybrid subscriptions, checkout captures the shipping address and displays the available shipping options with costs.
• On every recurring order, shipping options are recalculated, and Global-e automatically selects the shipping option matching the shopper’s first-order choice; if it’s unavailable for the destination, a comparable option is used (see Shipping option selection). Product restrictions are re-checked on each recurring order.
• Every order (first and recurring) is fulfilled from a single Global-e hub, resolved per order from its destination, with all physical order documents.
• The recurring shipping amount charged to the shopper is provided by the Subscription Manager; merchant shipping subsidies (e.g., free recurring shipping) are reflected in the value sent.

​

Subscription Manager Integration

• External subscription platforms own the subscription lifecycle - plan setup, invoicing, renewals, and cancellations.
• The Subscription Connector maps API/webhook communication between the subscription manager and Global-e.
• Each subscription contract ID received from the subscription manager is stored in Global-e and linked to the corresponding Global-e order for reconciliation and traceability.

​

Trials, Discounts & Billing Frequency

• Trials are represented as $0 orders in Global-e, allowing the shopper to complete checkout without payment capture.
• Billing cadence (monthly, annual, etc.) and recurring price are passed as parameters from the merchant’s platform and are used by Global-e to display the subscription terms clearly to the shopper during checkout.
• Hybrid carts containing both one-time and subscription items are supported.
• A subscription may contain multiple products, physical and digital (hybrid subscription), sharing a single billing frequency.

​

Security & Data Handling

• Global-e is fully PCI DSS compliant and handles tokenization internally.
• No raw payment data is shared with merchants or subscription managers.
• Tokens are deleted according to Global-e retention policy.

​

Business Processes Deep Dive

This section describes the full lifecycle of a subscription transaction, outlining how Global-e, the Subscription Manager, and the Merchant interact at each stage.

​

Plan & Contract Management (Merchant / Subscription Manager)

Overview: Merchants define and manage subscription plans in their chosen subscription manager. Global-e does not create, store, or manage plans or subscription contracts - it only processes transactions triggered by them. Key Assumptions:

• Subscription plans are equivalent to merchant-defined products.
• Trial duration, recurring price, and billing frequency are set in the subscription manager and passed to Global-e during checkout.
• Global-e receives these attributes at checkout for display and processing but does not store or modify plan logic.
• Subscription contract creation, cancellation, or updates are handled externally in the subscription manager.

​

First Subscription Order (Initial Checkout & Tokenization)

Overview: The first shopper interaction happens through Global-e checkout. If the cart includes any subscription product, it is treated as a subscription checkout. Hybrid carts are supported:

• A mixture of subscription + non-subscription items
• A mixture of Physical + digital products

Process:

1. Cart identification:
   • The eCommerce platform sends product level subscription attributes to Global-e (Subscription indication, Free Trial in Days, Recurring Price, Billing Frequency).
2. Checkout display:
   • Subscription details appear on the subscription products within the product summary, billing summary, and Terms & Conditions sections.
   • Only one billing frequency is supported per cart.
   • The Billing Summary shows a “Recurring” line with the total recurring amount - the sum of all subscription products’ recurring prices (shipping excluded).
   • The Terms & Conditions include the recurring charge disclosure (total recurring amount and billing frequency) and a shipping-fees disclaimer for physical recurring goods.
   • In some markets, the shopper must explicitly opt-in to subscription terms before completing payment.
3. Payment:
   • Only supported payment methods for subscription will be available for selection: credit cards and PayPal. Shopper enters payment details.
   • The first order follows Global-e’s standard payment timing (e.g., capture at dispatch), per the merchant’s configuration.
   • Free trials appear as $0 products and processes as 0$ payment
   • For a hybrid cart containing a non-subscription product and a free-trial subscription, the billing summary and payment reflect only the non-subscription product’s price.
4. Tokenization:
   • Global-e securely stores a tokenized payment reference.
   • For PayPal, Global-e receives a vaulted ID correlating to the stored payment method.
   • Tokens are stored in a PCI-secured environment for recurring use (MIT).
5. Order creation & notification:
   • Global-e creates an order with a subscription indicator at both order and product level.
   • The merchant creates the shopper’s subscription contract within the subscription manager.
   • Global-e stores the subscription contract ID and links it to the order and payment reference; it also stores the billing address, shipping method and address used for recurring orders

​

Billing Summary calculation (Shipping, Duties & Taxes)

Overview To ensure accurate shipping, tax and duty calculation for subscription renewals, Global-e support re-calculating the billing summary prior to each recurring billing attempt. This approach ensures compliance with current pricing, shipping options, tax rules, and regulatory requirements at the time of billing. Global-e remains the Merchant of Record (MOR) and is responsible for shipping options, tax and duty calculation logic, collection, and remittance. The Subscription Manager is responsible for triggering the calculation as part of the recurring billing flow. Process

1. Recurring Billing Preparation
   • Before initiating a recurring payment, the Subscription Manager identifies an upcoming renewal and determines the recurring charge amount.
2. Billing Summary Calculation
   • The Subscription Manager calls Global-e’s “Billing Summary calculation” API, providing the relevant transaction details (such as amount, currency, and product context).
   • For physical / hybrid subscriptions, Global-e calculates available shipping options for the destination using the same option as the shopper’s first-order. If that option is unavailable, a similar option is selected (see Shipping option selection).
   • Global-e calculates the applicable taxes and duties based on current rates, rules, and configuration.
3. Billing Execution
   • The calculated amounts (shipping, taxes, and duties) are used by the Subscription Manager when triggering the recurring payment request to Global-e.

Key Notes

• Shipping options, duties and taxes are recalculated for every recurring transaction, regardless of whether the recurring price has changed.
• This flow supports price changes, upgrades, downgrades, and regulatory or tax rate updates without additional conditional logic. Which means the result can legitimately differ from the previous cycle.
• The Subscription Manager does not calculate taxes, duties or shipping independently and relies on Global-e as the single source of truth.

​

Recurring Payments & Global-e Order Creation

Overview: Recurring payments are triggered by the subscription manager on each renewal date. Global-e processes the payment, performs fraud checks, and creates a new Global-e order upon success. Process:

1. Trigger & Invoice:
   • Subscription Manager identifies a due renewal and calls Global-e’s “Billing Summary calculation” API, providing the relevant transaction details.
   • Subscription Manager then uses the returned calculated amounts (shipping, taxes, and duties) while generating the invoice.
   • Subscription Manager sends a payment request (amount, currency, products, shipping amount, subscription ID) to the Subscription Connector.
   • Global-e Adapter validates: products Subtotal + duties + taxes + additional Fee + shipping − discounts = total Amount, otherwise order is rejected.
   • Shipping amount for physical/hybrid subscriptions reflects the Subscription Manager’s requested amount as-is; Global-e applies no recalculation or subsidy logic during payment processing.
2. Payment Execution:
   • Global-e retrieves tokenized payment details and sends a payment request to the payment gateway.
   • The recurring payment is charged immediately upon the Subscription Manager’s trigger - no dispatch delay applies to recurring orders
3. Fraud & Result Handling:
   • If payment fails → Global-e returns a failure response.
   • If successful → Global-e performs fraud checks each cycle.
     • Approved → Success response and order creation.
     • Challenged → Order created with “Fraud Challenge” status for manual review.
4. Order Creation:
   • On success, a new Global-e order is created, linked to the original subscription contract.
   • No fulfilment occurs unless the payment succeeds.
   • Subscription Manager marks the invoice as “Paid”.
5. Dunning Management:
   • Global-e does not manage retry or dunning logic.
   • Subscription Manager handles retries, customer notifications, and cancellations.
   • Global-e logs the payment failure reason for reference.

Key Highlights:

• Clear separation of responsibilities:
  • Global-e: on trigger - payment, fraud, shipping, order creation and fulfilment
  • Subscription Manager: lifecycle management, communication, dunning
• Fraud checks occur post-payment for consistency with Global-e flows.
• Each successful renewal creates a new Global-e order for fulfillment (physical/hybrid subscription), tracking and compliance.
• Global-e does not persist, validate or enforce the recurring product list, price or any discount. Those remain with the Subscription Manager.
• Global-e does not block the next cycle after a decline or fraud challenge order. Cross-cycle logic belongs in the Subscription Manager.

Notifications: who receives what

• Recurring payment status: Global-e Adapter to the Subscription Manager.
• Order and fulfilment status: standard Global-e order notifications to the merchant, not to the Subscription Manager.

​

Contract Management (Shopper Actions)

Overview: Shoppers manage their active subscriptions through the merchant’s portal or directly in the subscription manager interface. Supported Actions:

• Update Plan:
  • Managed by the Subscription Manager.
  • Includes: upgrades, downgrades, adding or removing products, quantity changes. All update the existing plan. No new checkout. No new subscription.
  • Global-e needs no notification. It charges any products and amounts sent on the next renewal trigger, which may differ from the previous order.
• Cancel Subscription:
  • Managed by the Subscription Manager.
  • Global-e deletes stored tokens as per Global-e retention policy
• Update Payment Details:
  • Shoppers can view and update stored payment methods via a Global-e–hosted, PCI-compliant widget. Global-e stores the new payment reference against the subscription, so future renewals use it.
  • The widget also provides the ability to edit the billing address, within the same country.
• Update Delivery Address:
  • Handled via a dedicated Global-e API: the Subscription Manager calls Global-e to validate and update the new subscription’s shipping address (same country only).
  • On success, the subscription details are updated and all future recurring orders ship to the new address.

Assumptions:

• Token retention and deletion policies are managed by Global-e.
• No direct shopper interaction with Global-e systems - all lifecycle management is via the merchant or subscription manager.

​

Solution Overview & Architecture

​

Conceptual Overview

The Subscription Connector allows each system to do what it does best:

• The Subscription Manager manages subscription plans, contracts, and billing schedules.
• Global-e manages localized checkout, payment authorization, recurring charges, shipping & fulfilment, and compliance.
• The Merchant integrates both systems to deliver a seamless experience to shoppers.

​

High-Level Flow

Checkout (First Order)

• Shopper selects a subscription product on the merchant’s storefront.
• The eCommerce platform passes product-level subscription attributes (e.g., trial days, recurring price, billing frequency) to Global-e checkout. (see more information here)
• Subscription details appear on the subscription product summary, billing summary, and Terms & Conditions sections.
• Global-e processes the first payment (or $0 if a trial) and securely tokenizes the payment details.
• Global-e creates the initial order and sends the order confirmation to the eCommerce platform.
• Following a successful order, the merchant triggers subscription creation in the Subscription Manager.
• The Subscription Manager creates the subscription contract and notifies Global-e with the newly created subscription ID. (see more information here)
• Global-e stores the subscription ID together with the payment reference (tokenized payment details) billing address, shipping address and shipping method for use in future recurring transactions.

Recurring Payment

• Prior to triggering the recurring payment the Subscription Manager calls Global-e “Billing Summary calculation” API to retrieve the selected shipping option and the applicable tax and duty amounts for the upcoming charge. (see more information here)
• On each renewal, the Subscription Manager triggers a payment attempt to Global-e using the subscription ID. (see more information here)
• Global-e processes the payment, performs fraud checks, and creates a Global-e order upon success.
• In case of payment failure, Global-e provides the failure reason, and the Subscription Manager handles retries and dunning logic.

Contract Management

• Shoppers manage their subscriptions (update, cancel, change plan) via the merchant’s account area or the Subscription Manager portal.
• Update Payment Method: The merchant displays the current payment method using a Global-e API, and host Global-e secure widget that allows shoppers to update their stored payment details, including the billing address (same country only). (see more information here)
• Update Delivery Address: the Subscription Manager calls Global-e’s subscription update API to validate and apply a same-country shipping address change, applied to all future recurring orders.

​

Architectural Components

​

Architecture Summary

• Global-e and the Subscription Manager communicate via the Subscription Connector using APIs and webhooks.
• The connector ensures secure, PCI-compliant payment execution for recurring transactions.
• Each renewal is represented as a new Global-e order, ensuring continuity in reporting and compliance as well as fulfillment of physical subscriptions products.

​

Shipping option selection

Below logic describes shipping option selection for physical subscriptions

​

Where to go next

​

API reference

Every endpoint in the Subscriptions set, with its full request and response contract: