Subscription Connector (End-to-End)

Part of the Subscriptions Overview — see it for the end-to-end business flow, roles and responsibilities, and capabilities.

Conceptual Overview

API Endpoints Summary

Direction	Method	Endpoint	Purpose
Subscription Manager to Global-e	POST	`/subscriptions/notifications` Endpoint contract	This endpoint allows the Subscription Manager to inform Global-e about subscription lifecycle events, such as “SUBSCRIPTION_CREATED”
Subscription Manager to Global-e	POST	`/subscriptions/billing-summary/calculate` Endpoint contract	This endpoint allows the Subscription Manager to request a billing summary calculation - the selected shipping option and duties and taxes - before processing recurring payments.
Subscription Manager to Global-e	POST	`/subscriptions/recurringPayments` Endpoint contract	This endpoint allows the Subscription Manager to trigger Global-e to process a recurring payment and subsequent order creation.
Global-e to Subscription Manager	POST	`/subscriptions/recurringPayments/notifications` Endpoint contract	Global-e calls this endpoint to notify Subscription Manager about the status of recurring payments.
Subscription Manager to Global-e	PATCH	`/subscriptions/{subscriptionId}` Endpoint contract	This endpoint allows the Subscription Manager to update a subscription shipping (delivery) address, same country only.
Merchant to Global-e	GET	`/Payments/Subscriptions/{merchantGuid}` Endpoint contract	Returns the current masked payment method and billing address per subscription ID, for display in the merchant portal.
Merchant to Global-e	JS SDK	`GlobalE.UpdatePaymentMethod()` See document	Launches the Global-e update payment widget on the merchant page so the shopper can change the payment method on an active subscription.

Checkout (First Order)

To initiate the subscription purchase behavior on checkout, the eCommerce platform passes product-level subscription attributes to Global-e on the cart. The attributes are passed per subscription product; multiple subscription products in one cart are supported, sharing one billing frequency. The required attributes are:

Key	Description	Example	Notes
ProductType	Subscription indication	4	4 means a subscription product, 0 means a one-time sale product
FreeTrialDays	Free trial duration in days	7	0 or null means no trial
RecurringPrice	Recurring charge amount	14.99	In shopper currency
BillingFrequency	Frequency of recurring billing	Weekly	Possible values: Daily, Weekly, Monthly, Annually

Once the shopper decides to purchase the subscription, Global-e processes the first payment (or $0 if a trial), securely tokenizes the payment details and creates the initial order on Global-e platform. The following shows the flow sequence after first order completed:

Recurring Payment

The following figure shows the Recurring Payment flow sequence:

Contract Management (Shopper Actions)

Update payment method Subscribers can change the payment method on an active subscription. Global‑e provides a secure, hosted widget for the change itself. Credit cards and PayPal are supported, including switching between them. 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. The merchant calls Get subscription and payment reference details on the Global‑e Web domain (for example web.global-e.com) to display the shopper’s current masked payment method and billing address, then loads the Global‑e payment form as an iFrame on its own page. That call is server-to-server only — the merchantGuid it takes is a secret key that identifies the merchant and must not be exposed in browser-side code.

Card details are entered inside the Global‑e hosted iFrame and never reach the merchant page or server, keeping the merchant out of PCI scope for this flow.

The following figure shows the Update Payment flow sequence:

Before calling the method:

globale.merchant.client.js must be loaded so that GlobalE is available globally.
The DOM element identified by container must exist before calling UpdatePaymentMethod.

GlobalE.UpdatePaymentMethod(
  "subscription-123",
  "en-US",
  "USD",
  "updatePaymentMethodContainer",
  function (data) { console.log("Success", data); },
  function (info) { console.log("Canceled", info); },
  function (err) { console.log("Failure", err.error || err.message); },
  "MerchantReturnUrl"
);

The signature, parameters, callbacks and result codes are documented on the GlobalE.UpdatePaymentMethod page. Update delivery address The Subscription Manager calls the subscription update API (PATCH /subscriptions/{subscriptionId}); Global-e validates the new address (same country only) and updates the subscription details, so all future recurring orders ship to the new address. See flow details here

Authentication and Security

The endpoints the Subscription Manager calls accept either a JWT bearer token or an API key, both issued to the Subscription Manager by Global-e. For how to obtain and renew a JWT token, see API Authentication. To use the API key instead, pass it in the x-api-key header:

x-api-key: {api key value}

Get subscription and payment reference details is the exception: the merchant calls it, not the Subscription Manager, and it identifies the merchant by the merchantGuid in its path rather than by either of these credentials. That value is a secret key — issue the call server-to-server and keep it off the browser.

Idempotency

Every endpoint in the Subscriptions set requires an Idempotency-Key header. It is a UUID that identifies the request, so that the operation is applied at most once however many times it arrives:

Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Send the same value again when you retry a request that timed out or failed in transit. Send a new value for a new operation: a key that has already been processed is rejected with 409.

{
  "error": "Idempotency key conflict",
  "code": "IDEMPOTENCY_KEY_CONFLICT",
  "description": "Request already in use. Use a different Idempotency-Key for new operation."
}

API reference

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

Subscription notifications

POST /subscriptions/notifications

Calculate billing summary

POST /subscriptions/billing-summary/calculate

Create recurring payment

POST /subscriptions/recurringPayments

Recurring payment notifications

POST /subscriptions/recurringPayments/notifications

Update a subscription

PATCH /subscriptions/{subscriptionId}

Get subscription and payment reference details

GET /Payments/Subscriptions/{merchantGuid} — called by the merchant, server-to-server

​Conceptual Overview

​Checkout (First Order)

​Recurring Payment

​Contract Management (Shopper Actions)

​Authentication and Security

​Idempotency

​API reference

Subscription notifications

Calculate billing summary

Create recurring payment

Recurring payment notifications

Update a subscription

Get subscription and payment reference details

Conceptual Overview

Checkout (First Order)

Recurring Payment

Contract Management (Shopper Actions)

Authentication and Security

Idempotency

API reference