> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Connector (End-to-End)

Part of the [Subscriptions Overview](/subscriptions) — 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](/api-reference/subscription-notifications) | 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](/api-reference/calculate-billing-summary) | 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](/api-reference/create-recurring-payment) | 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](/api-reference/recurring-payment-notifications) | 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](/api-reference/update-subscription) | 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](/api-reference/get-subscription-and-payment-reference-details) | 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](/globale-updatepaymentmethod) | 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**:

<Frame>
  <img src="https://mintcdn.com/globale-enterprise/ZiykvHZPz1ojekrf/images/subscriptions/subscription-connector-first-order-flow.png?fit=max&auto=format&n=ZiykvHZPz1ojekrf&q=85&s=c5420c0ff8d41ce689aca2dc2a26ef04" width="724" height="468" data-path="images/subscriptions/subscription-connector-first-order-flow.png" />
</Frame>

### Recurring Payment

The following figure shows the Recurring Payment flow sequence:

<Frame>
  <img src="https://mintcdn.com/globale-enterprise/ZiykvHZPz1ojekrf/images/subscriptions/subscription-connector-recurring-payment-flow.png?fit=max&auto=format&n=ZiykvHZPz1ojekrf&q=85&s=046b8a7e4ef26a81141dd51235362f52" width="783" height="858" data-path="images/subscriptions/subscription-connector-recurring-payment-flow.png" />
</Frame>

### 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](/api-reference/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.

<Note>
  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.
</Note>

The following figure shows the Update Payment flow sequence:

<Frame>
  <img src="https://mintcdn.com/globale-enterprise/ZiykvHZPz1ojekrf/images/subscriptions/subscription-connector-update-payment-flow.png?fit=max&auto=format&n=ZiykvHZPz1ojekrf&q=85&s=3e22d322b0c2fc9c8cde8eec17c45339" width="378" height="541" data-path="images/subscriptions/subscription-connector-update-payment-flow.png" />
</Frame>

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.

```js theme={null}
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](/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](/subscription-connector#recurring-payment)

## 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](/api-authentication). To use the API key instead, pass it in the `x-api-key` header:

```http theme={null}
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:

```http theme={null}
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`.

```json theme={null}
{
  "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:

<div className="api-ref-card">
  <Card title="Subscription notifications" icon="bell" href="/api-reference/subscription-notifications">
    `POST /subscriptions/notifications`
  </Card>

  <Card title="Calculate billing summary" icon="calculator" href="/api-reference/calculate-billing-summary">
    `POST /subscriptions/billing-summary/calculate`
  </Card>

  <Card title="Create recurring payment" icon="credit-card" href="/api-reference/create-recurring-payment">
    `POST /subscriptions/recurringPayments`
  </Card>

  <Card title="Recurring payment notifications" icon="webhook" href="/api-reference/recurring-payment-notifications">
    `POST /subscriptions/recurringPayments/notifications`
  </Card>

  <Card title="Update a subscription" icon="location-dot" href="/api-reference/update-subscription">
    `PATCH /subscriptions/{subscriptionId}`
  </Card>

  <Card title="Get subscription and payment reference details" icon="wallet" href="/api-reference/get-subscription-and-payment-reference-details">
    `GET /Payments/Subscriptions/{merchantGuid}` — called by the merchant, server-to-server
  </Card>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.