Configuration - Global-e Docs

After uploading cartridges and importing metadata, configure the site in Business Manager. Cartridge selection and path rules are summarized in Cartridges. When the Staging setup is complete, use Production readiness to promote it to Production.

Add Global-e cartridges to the site cartridge path

Administration > Sites > Manage Sites > (Your Site) > [Settings Tab] Global-e cartridges follow Salesforce Commerce Cloud standards. After adding them on a demo SiteGenesis or SFRA storefront, the site should be ready for basic Global-e flows. Customize int_globale_sitegenesis (SiteGenesis) or int_globale_sfra (SFRA) for brand-specific logic.

SiteGenesis Pipelines or Controllers

Add int_globale_sitegenesis and int_globale before your brand cartridges (left = highest priority). Example:

int_globale_sitegenesis:int_globale:<your-brand-cartridges>:sitegenesis_storefront_controllers:sitegenesis_storefront_core

SFRA

Add int_globale_sfra and int_globale after your brand cartridges and before app_storefront_base (left = highest priority). Example:

<your-brand-cartridges>:int_globale_sfra:int_globale:app_storefront_base

Business Manager (organization job steps)

Add int_globale to the Business Manager cartridge path so organization-context GlobaleSettings steps can load cartridge scripts (for example GlobaleUpdateCachePriceBooksConfigHash). Configure manually in Business Manager or via b2c sites cartridges add int_globale --bm --position first — see Cartridges § Business Manager cartridge path.

Headless / PWA

Add int_globale_headless with int_globale:

Headless only — int_globale_headless : int_globale (no SFRA/SiteGenesis storefront cartridge)
Headless + SFRA site — place int_globale_headless immediately before int_globale_sfra so Shop OCAPI hooks register for the site

Set site preference geCAPIType to OCAPI or SCAPI as agreed with Global-e. See Hooks § Headless and Metadata § Global-e OCAPI / SCAPI Settings.

Default Currency Settings

Administration > Sites > Manage Sites > (Your Site) > General For all Global-e operated sites, Default Currency must be a base merchant currency (for example GBP or USD — not a Global-e operated shopper currency).

Order Preferences (Merchant Tools > Site Preferences > Order)

Limit Storefront Order Access

Set this preference to Allow List and add the following Global-e endpoints:

Globale-CustomerRegistration
Globale-ValidateCart
Globale-OrderCreate
Globale-OrderCreateV2
Globale-OrderSendToMerchant
Globale-OrderPerformPayment
Globale-OrderUpdateStatus
Globale-OrderUpdateShippingInfo
Globale-OrderRefund
Globale-OrderRMA
Globale-Coupon
Globale-ClearCart
Globale-VoidInventoryReservation (SFRA only — this endpoint is implemented in int_globale_sfra; it is not registered in the SiteGenesis controller)

Enter the controllers as a comma-separated list in the Allow List field (Business Manager accepts other separators and normalizes them).

Filter Storefront Orders by Customer Session

Set to No.

Failed Orders Settings

By default this field is empty, so SFCC does not auto-fail orders in CREATED status. Set a timeout in minutes — for example 4320 (3 days). If Global-e account setting Place Order On Payment Update is Yes, set Auto-Fail Orders longer — for example 20160 (14 days).

Payment Processor (Merchant Tools > Ordering > Payment Processors)

Create the GLOBALE payment processor manually (New → Processor ID GLOBALE, description such as Global-e Payment Processor). After importing metadata/site/paymentmethod.xml you will have payment method GLOBALE (Globale). Assign it to payment processor GLOBALE (metadata does not create the processor).

Shipping methods (Merchant Tools > Ordering > Shipping Methods)

After importing metadata/site/shippingmethods.xml you will have Global-e shipping methods (IDs start with GLOBALE — for example GLOBALE, GLOBALE_STANDARD, GLOBALE_EXPRESS). These methods are placeholders so Salesforce B2C Commerce can create SFCC orders correctly — they are not live Global-e carrier methods. After a fresh import, open each Global-e shipping method and verify Tax Class is Standard or a valid custom tax class — not Undefined (a fresh import can reset it).

Site Preferences (Merchant Tools > Site Preferences > Custom Site Preference Groups)

Global-e Settings

Obtain merchant details (Client JS Merchant ID, Merchant GUID, API base URL, and SDK base URL) from your Global-e project manager. Site preferences — in Merchant Tools > Site Preferences > Custom Site Preference Groups > Global-e Settings, set:

Preference	Description
Global-e Enabled (`geEnabled`)	Set to Yes when the site is ready for Global-e.
Global-e API Base URL (`geApiUrl`)	Base URL for outbound Global-e API calls (for example `https://connect.bglobale.com`). Environment-specific; set per site.
Service Endpoint Config (`geServiceEndpointConfig`)	Optional JSON map of per-service URL and/or credential overrides (see Services configuration).
Client JS Merchant ID (`geClientJsMerchantId`)	Your numeric merchant account ID from Global-e (for example `10001`). Used by the storefront SDK and as the suffix for merchant GUID credentials.
Global-e Client JS SDK Base URL (`geClientJsBaseUrl`)	Base URL for loading the Global-e client SDK (environment-specific; provided by Global-e).

Merchant GUID credentials (required)

Metadata import creates Global-e service instances and a placeholder credential Globale-MerchantAccount (empty URL and password). That stub satisfies SFCC wiring only — it is not your merchant account. You must create account ID credentials manually for every Global-e merchant account used on the instance. In Administration > Operations > Services > Credentials, create:

Credential ID	Required when	URL	Password
`Globale-{geClientJsMerchantId}`	Every site using that merchant account (for example `Globale-10001` when Client JS Merchant ID is `10001`)	Empty	Merchant GUID (UUID from Global-e)

Rules:

One credential per merchant account ID on the instance (not per site). If two sites use merchant ID 10001, they share Globale-10001; set geApiUrl per site for environment (INT, QA, HF, etc.).
If multiple merchant accounts are used (for example 10001 and 10002), create Globale-10001 and Globale-10002.
The cartridge reads API base URL from site preference geApiUrl and Merchant GUID from the credential Password for outbound calls and inbound request validation.
Optional extra credentials (password only), for example Globale-10001-PROD, only when a site uses geServiceEndpointConfig to point a specific service at a different protected GUID — see Services configuration.

Without Globale-{merchantId} credentials, outbound API calls and inbound Global-e callbacks (cart validation, order notifications, etc.) will fail. Per-service endpoint overrides — optional site preference geServiceEndpointConfig (JSON) in the Global-e Settings group. Keys are SFCC service IDs (for example Globale-RecentProductCountryS). Values are a relative path or full https:// URL, or an object { "url": "...", "credentialId": "Globale-10001-PROD" } when a service must use a different protected GUID credential. When empty, cartridge defaults apply with geApiUrl.

Global-e Product Settings

In Merchant Tools > Site Preferences > Custom Site Preference Groups > Global-e Product Settings, set Product Image ViewType (geProductImageViewType) to the catalog view type whose URLs should be sent to Global-e (for example large). Other GLOBALE-PRODUCT preferences are optional but recommended. Full descriptions and examples are in Metadata.

Global-e OCAPI Settings

In Merchant Tools > Site Preferences > Custom Site Preference Groups > Global-e OCAPI Settings, set:

Preference	Description
OCAPI Version (`geOCAPIVersion`)	Required for headless / OCAPI integrations. Use a different format than the system OCAPI version — for example system version `21.3` maps to `v21_3`.
OCAPI Client ID (`geOCAPIClientId`)	Required whenever `geCAPIType` uses OCAPI. Dedicated Account Manager API client — do not reuse the Data OCAPI client.

These preferences are not flagged mandatory in the metadata schema; set them whenever the site uses OCAPI.

Price Books (Merchant Tools > Products and Catalogs > Price Books)

See Price Calculation for configuration options and use cases.

Pipeline URLs mapping (Merchant Tools > SEO > URL Rules)

Go to Business Manager > Site > Merchant Tools > Site URLs > URL Rules > Pipeline URLs and set:

Alias	Pipeline
globale/checkout/pspredirect	Globale-PaymentRedirect

Open Commerce API Settings (Administration > Site Development > Open Commerce API Settings)

Global-e uses OCAPI in two ways. Configure each with a dedicated Account Manager API client — do not reuse the same client for Shop and Data.

Shop API (headless / Commerce API)

Configure Shop API permissions for your headless OCAPI client. A reference template is in the repository at metadata/ocapi-settings/wapi_shop_config.json. Adjust _v and client_id for your instance; include at least basket read/update, coupon, session, customer auth, and order create:

{
  "_v": "24.5",
  "clients": [
    {
      "client_id": "your-account-manager-client-id",
      "resources": [
        {
          "resource_id": "/customers/auth",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/sessions",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/baskets/*",
          "methods": ["get", "patch", "delete"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/baskets/*/coupons",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/baskets/*/coupons/*",
          "methods": ["delete"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/orders",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        }
      ]
    }
  ]
}

Headless integrations also require int_globale_headless on the cartridge path — see Hooks § Headless.

Data API (mandatory for new integrations)

New Global-e SFCC integrations must create a dedicated Account Manager API client and grant it Data OCAPI permissions in Business Manager (type Data, context Global). Global-e uses this client over OCAPI to keep your storefront configuration aligned with Global-e — for example starting configuration sync jobs such as GlobaleSettings, and reading related Global-e custom objects, site preference groups, and product information. The resource list below defines the full access scope. Salesforce references: Client Application Identification, OCAPI Settings.

In Account Manager, create an API client (display name such as Global-e Integration), assign it to the organization and instances Global-e must call, set a password (OAuth client secret), and copy the API Client ID. Keep the client Enabled.

In Business Manager → Administration → Site Development → Open Commerce API Settings, select type Data and context Global. Paste the JSON below (or start from metadata/ocapi-settings/wapi_data_config.json), replace client_id with the Account Manager client ID, then Save. _v is the OCAPI Settings document version (not the API URL version such as v21_10). Settings can take a few minutes to become effective.

Share the following with Global-e over a secure channel: client ID, password (client secret), SFCC base URL(s), and the OCAPI Data API version used on your instance (path segment such as v21_10).

{
  "_v": "24.5",
  "clients": [
    {
      "client_id": "your-account-manager-client-id",
      "allowed_origins": [],
      "resources": [
        {
          "resource_id": "/jobs/*/executions",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/jobs/*/executions/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(**)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_APP_SETTINGS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_COUNTRIES/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_COUNTRY_COEFFICIENTS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_PRODUCT_CLASS_COEFFICIENTS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_CULTURES/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_CURRENCIES/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_CURRENCY_RATES/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_ROUNDING_RULES/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_CACHE_PRICE_BOOK_COMBINATION/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_HUB_DETAILS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_ORDER_NOTIFICATION/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_INBOUND_ORDER_FALLBACK/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_INVENTORY_NOTIFICATION/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_RESTRICTED_ITEMS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_COUPON_REDEMPTIONS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/custom_objects/GLOBALE_LOCAL_STORAGE/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/site_preferences/preference_groups/GLOBALE/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/site_preferences/preference_groups/GLOBALE-PRODUCT/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/site_preferences/preference_groups/GLOBALE-OCAPI/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/site_preferences/preference_groups/GLOBALE-SCAPI/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/sites/*/site_preferences/preference_groups/GLOBALE-CATALOG-JOBS/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/product_search",
          "methods": ["post"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/products/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/products/*/variation_groups",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/products/*/variation_groups/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/products/*/variations",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        },
        {
          "resource_id": "/products/*/variations/*",
          "methods": ["get"],
          "read_attributes": "(**)",
          "write_attributes": "(none)"
        }
      ]
    }
  ]
}

If Global-e needs additional OCAPI resources later, add the corresponding entries under resources.

Services (Administration > Operations > Services)

After importing metadata/services.xml you will have Global-e service instances (IDs start with Globale-) and the placeholder credential Globale-MerchantAccount. Service paths and API base URLs are not configured in per-endpoint credentials — they come from cartridge defaults, site preference geApiUrl, and optional geServiceEndpointConfig. You must still create Globale-{merchantId} merchant GUID credentials manually — see Merchant GUID credentials (required). Disable rate limiting on Globale-SendCartV2 and enable communication logging on all Global-e services for at least the first few weeks after production launch.

Scheduled Jobs (Administration > Operations > Jobs)

After importing metadata/jobs.xml you will have Global-e jobs (IDs start with Globale). Run the GlobaleSettings job manually to pull configuration from Global-e into GLOBALE_* custom objects. After you complete Data API setup, Global-e can also start this sync over OCAPI when configuration changes. All Global-e jobs except GlobaleSettings are disabled by default — adjust schedules per your integration scope. Assign GlobaleSettings job flows only to sites operated by Global-e. For job purpose, step details, and scheduling guidance, see Jobs.

​Add Global-e cartridges to the site cartridge path

​SiteGenesis Pipelines or Controllers

​SFRA

​Business Manager (organization job steps)

​Headless / PWA

​Default Currency Settings

​Order Preferences (Merchant Tools > Site Preferences > Order)

​Limit Storefront Order Access

​Filter Storefront Orders by Customer Session

​Failed Orders Settings

​Payment Processor (Merchant Tools > Ordering > Payment Processors)

​Shipping methods (Merchant Tools > Ordering > Shipping Methods)

​Site Preferences (Merchant Tools > Site Preferences > Custom Site Preference Groups)

​Global-e Settings

​Merchant GUID credentials (required)

​Global-e Product Settings

​Global-e OCAPI Settings

​Price Books (Merchant Tools > Products and Catalogs > Price Books)

​Pipeline URLs mapping (Merchant Tools > SEO > URL Rules)

​Open Commerce API Settings (Administration > Site Development > Open Commerce API Settings)

​Shop API (headless / Commerce API)

​Data API (mandatory for new integrations)

​Services (Administration > Operations > Services)

​Scheduled Jobs (Administration > Operations > Jobs)