> ## 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.

# GlobaleOrderStatusFallback

<Note>
  **Optional feature.** This job ships with the Global-e SFCC cartridges but is **disabled by default** and must **not** be turned on until Global-e has enabled SFTP order-status export for the merchant. See [Order status SFTP fallback](/order-status-sftp-fallback-sfcc).
</Note>

**GlobaleOrderStatusFallback** is a durable fallback for inbound Global-e → SFCC order status updates when the live webhook (`Globale-OrderUpdateStatus`) is unavailable or delayed.

Global-e writes status-update JSON files to a shared SFTP folder. Each SFCC site flow downloads only files whose name starts with that site’s ID (`{SiteID}_…`), enqueues them as custom objects, then applies the same status-update logic used by the webhook. Already-applied updates are skipped using the `OrderStatusUpdateTime` token stored on the order.

See also: [Optional feature overview](/order-status-sftp-fallback-sfcc), [Jobs overview](/jobs-sfcc), [Order lifecycle](/order-lifecycle-sfcc), [Metadata](/metadata-sfcc).

## When to use it

Use this job only when:

1. Global-e has **enabled** SFTP export of failed/offline `UpdateOrderStatus` notifications for the merchant, and
2. SFTP host/credentials and remote folder have been agreed with Global-e, and
3. SFCC metadata/code for this feature is deployed and validated on a non-production instance.

Keep the schedule **disabled** until those conditions are met. The live webhook remains the primary channel; this job is complementary and must not re-apply status updates the webhook already processed (deduplication is built in).

## Job steps

| Step | Step type | Description |
| - | - | - |
| DownloadOrderStatusFiles | `custom.GlobaleDownloadOrderStatusFiles` | Lists the remote SFTP directory, downloads configured `{WebStoreCode}_*.json` files (bounded batch), then deletes or archives each remote file |
| EnqueueOrderStatusFiles | `custom.GlobaleEnqueueOrderStatusFiles` | Parses local JSON files into `GLOBALE_INBOUND_ORDER_FALLBACK` custom objects; deletes local files after enqueue (or after logging invalid JSON) |
| ProcessOrderStatusFallbackQueue | `custom.GlobaleProcessOrderStatusFallbackQueue` | Drains the CO queue in key order, applies each status update, removes the CO on success/dedup-skip/maxAttempts/invalid JSON; retains on retryable failure |

Default site context in `metadata/jobs.xml` is `RefArchGlobal`. Replace it with your Global-e site ID(s). Add one job flow per SFCC site that should consume the feed. When Global-e `WebStoreCode` values differ from the SFCC site ID (or several codes map to one site), set the **`webStoreCodes`** step parameter.

## High-level flow

1. Global-e drops files named `{WebStoreCode}_{…}_{OrderStatusUpdateTime}.json` on SFTP (shared folder).
2. **Download** — for the current site context, only files whose name starts with a configured WebStoreCode prefix are downloaded to IMPEX. By default the prefix is the SFCC site ID; override with `webStoreCodes` when needed. Other prefixes stay on SFTP for their own flows.
3. **Enqueue** — each valid payload becomes a site-scoped `GLOBALE_INBOUND_ORDER_FALLBACK` custom object (key = file name).
4. **Process** — COs are applied in ascending key order (lexicographic = time order for fixed-width `OrderStatusUpdateTime`). Per-order short-circuit: if an earlier event for an order fails, later events for that same order are skipped this run so sequence is preserved.
5. On successful apply **or** dedup skip, SFCC best-effort calls Global-e **CreateOrderLog** (type `365`, `IsSuccess: true`). On apply failure (or invalid CO JSON), SFCC also best-effort logs with the same type (`IsSuccess: false`, `LogLevelId: 4`).

## Business Manager setup

### 1. Import metadata

Import job, service, and custom-object metadata from the cartridge package (`metadata/jobs.xml`, `metadata/services.xml`, `metadata/meta/*`). Confirm:

* Job **GlobaleOrderStatusFallback** exists under **Administration → Operations → Jobs**
* Service **Globale-SFTPDownload** (SFTP) and **Globale-CreateOrderLog** (HTTP) exist under **Administration → Operations → Services**
* Custom object type **GLOBALE\_INBOUND\_ORDER\_FALLBACK** exists
* Order attribute **geAppliedStatusOperationIds** exists (CSV of already-applied `OrderStatusUpdateTime` values)

### 2. Configure SFTP download credentials

Open **Globale-SFTPDownload** credentials in Business Manager and set host, user, password (and path if required by your SFTP layout). The job step parameter `sftpCredentialID` defaults to `Globale-SFTPDownload`.

### 3. Configure CreateOrderLog (optional but recommended)

Set the HTTP service base URL / credential for **Globale-CreateOrderLog** (`/GEPI/CreateOrderLog`) so fallback applies and apply failures can notify Global-e. Failures of this HTTP call never block status application.

Keep **mock-mode** off in environments where you want real feedback to Global-e.

### 4. Configure the job step parameters

On **DownloadOrderStatusFiles**:

| Parameter | Default | Notes |
| - | - | - |
| `sftpCredentialID` | `Globale-SFTPDownload` | Must match a configured SFTP credential |
| `remoteDir` | `/catalog/order-status` | Shared remote folder from Global-e |
| `remoteFileHandling` | `Delete` | `Delete` (default) or `Archive` after successful download |
| `remoteArchiveDir` | `/catalog/order-status/archive` | Used only when `remoteFileHandling` = `Archive` |
| `maxFilesPerRun` | `100` | Caps files processed per run |
| `webStoreCodes` | *(empty → current site ID)* | Comma-separated Global-e WebStoreCode prefixes for this flow (e.g. `RefArchGlobal,MyBrand-GBP`). Use when codes differ from the SFCC site ID or several codes belong to one site |
| `geDisableJobStep` | `false` | Set `true` to skip a step without removing it |

On **ProcessOrderStatusFallbackQueue**:

| Parameter | Default | Notes |
| - | - | - |
| `maxAttempts` | `5` | Failed apply attempts per CO before the CO is removed (CreateOrderLog still sent). Platform retention (5 days) is a safety net if the job is off |
| `geDisableJobStep` | `false` | Set `true` to skip a step without removing it |

### 5. Site flows and schedule

* Assign each flow’s **site context** to the SFCC site that should apply the updates.
* Set **`webStoreCodes`** when file prefixes are not identical to that site ID (supports multiple codes per site).
* Recurring trigger is **disabled by default** (every 15 minutes when enabled), same pattern as **GlobaleOrderNotifications**.
* Enable the trigger only after a successful manual run.

## IMPEX folder layout

Per merchant / site:

```text theme={null}
IMPEX/src/globale/orderStatusFallback/{merchantId}/{SiteID}/
  └── *.json                 # inbound only (deleted after enqueue or on invalid JSON)
```

`merchantId` comes from site preference **Client JS Merchant Id** (`geClientJsMerchantId`).

## Custom object queue

| Item | Value |
| - | - |
| Type | `GLOBALE_INBOUND_ORDER_FALLBACK` |
| Scope | Site |
| Retention | 5 days |
| Key (`ID`) | Source file name |
| Payload | `geNotificationPayload` (JSON text, webhook-equivalent body) |
| Attempts | `geAttemptCount` (failed apply count; removed at `maxAttempts`) |

### CO lifecycle

| Outcome | CO action |
| - | - |
| Status applied successfully | Removed; CreateOrderLog success |
| Dedup skip (`OrderStatusUpdateTime` already on the order) | Removed; CreateOrderLog success |
| Apply failed (attempt \< `maxAttempts`) | Retained; `geAttemptCount` incremented; later events for the same order short-circuited this run |
| Apply failed (attempt ≥ `maxAttempts`) | Removed; failure CreateOrderLog; later events for the same order may proceed |
| Invalid JSON in CO | Removed immediately; failure CreateOrderLog |

## Deduplication

Both the webhook and this job record applied `OrderStatusUpdateTime` values in order custom attribute **geAppliedStatusOperationIds** (comma-separated). If the same token arrives again on either channel, the update is skipped and an order note is written.

## Logging and troubleshooting

| Symptom | What to check |
| - | - |
| No files downloaded | `webStoreCodes` / site ID vs file names; `remoteDir`; SFTP credential; `maxFilesPerRun` |
| Other site’s files left on SFTP | Expected — only configured WebStoreCode prefixes are downloaded |
| Invalid / unparseable JSON | File deleted after error log; inspect **GLOBALE** logs (`GE_SFTP_FALLBACK_EnqueueOrderStatusFiles`); encoding should be UTF-8 |
| CO retained across runs | Order missing in SFCC, MerchantGUID mismatch, or apply error in **GLOBALE** logs (`GE_SFTP_FALLBACK_*`); check `geAttemptCount` vs `maxAttempts` |
| CO removed after repeated failures | Expected when `geAttemptCount` reaches `maxAttempts` — check CreateOrderLog / job log `exhausted` count |
| Status not changing on duplicate file | Expected dedup — check `geAppliedStatusOperationIds` and order notes |
| CreateOrderLog missing in Global-e | Service enabled, mock mode off, API host/cred; apply still succeeds without it |

Configure the **GLOBALE** custom log under **Administration → Site Development → Development Setup → Custom Log Settings**.