> For the complete documentation index, see [llms.txt](https://docs.hotwax.co/documents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hotwax.co/documents/learn-shopify/shopify-reference/orders/order-download.md).

# Order Download

Understand and monitor Shopify order imports after launch.

Use this reference after a Shopify shop is live to identify which order import flow should have processed an order. For initial setup, history reconciliation, and launch validation, follow [Set up HotWax Commerce with Shopify](https://github.com/hotwax/oms-documentation/tree/user-guides-pub/documents/system-admin/administration/company/product-store-onboarding.md).

## Flow summary

| Flow     | Trigger                                                                         | Purpose                                                                                                                                             |
| -------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| History  | Controlled `sync_ShopifyOrderHistory` windows                                   | Imports eligible open and unfulfilled orders from before launch.                                                                                    |
| Realtime | Shopify `ORDERS_CREATE` and `ORDERS_UPDATED` events through EventBridge and SQS | Processes new orders and later order updates soon after Shopify emits them. The create event provides a direct path for high-volume order creation. |
| Fallback | Recurring shop-specific `queue_ShopifyOrderSync` job                            | Provides a scheduled recovery path for eligible order updates.                                                                                      |

Monitor each flow independently. A positive result in one flow does not prove that either of the other flows is healthy.

```mermaid
flowchart TD
    accTitle: Trace separate Shopify order import paths
    accDescr: History uses a bulk-query system message, realtime uses an EventBridge and SQS consumer job, and fallback uses a queued system message. Check the tied Data Manager result and the same Shopify order in HotWax for each path.
    History[Controlled history window] --> HistoryMessage[Bulk query<br/>system message]
    HistoryMessage --> HistoryImport[History import<br/>Data Manager result]
    Event[Shopify create or<br/>update event] --> SQS[EventBridge and SQS<br/>consumer job]
    SQS --> RealtimeImport[Realtime import<br/>Data Manager result]
    Batch[Scheduled fallback batch] --> BatchMessage[Queued system message]
    BatchMessage --> BatchImport[Fallback import<br/>Data Manager result]
    HistoryImport --> Verify[Verify the same Shopify order<br/>in HotWax Commerce]
    RealtimeImport --> Verify
    BatchImport --> Verify
```

For eligible work that proceeds to import, follow its own path to the Data Manager result and matching OMS order. Realtime imports link to the SQS consumer job run rather than a System Message; keep that evidence trail separate from history and fallback batches.

## Historical open-order import

History import is not a complete Shopify order archive. It queries open and unfulfilled orders in controlled `updatedAt` windows. An order can therefore enter a history window because Shopify updated it during that window, even when Shopify created it earlier.

For an order that does not already exist in HotWax Commerce, `createdAt < newOrderSync.launchDate` determines whether it is created as historical work. Existing orders are updated rather than recreated. Historical pre-launch orders use `needsInventoryIssuance=N`, and their unfulfilled ship groups are parked in `GENERAL_OPS_PARKING` until normal processing takes over.

For every history window, retain:

* Exact converted start and end timestamps.
* History job-run identifier.
* `BulkOrderHistoryQuery` `systemMessageId`.
* Terminal `BULK_ORDER_HISTORY` Data Manager result.
* Reconciliation showing that eligible orders were created, existing orders were not duplicated, and adjacent windows have no gap or overlap.

If a window fails after the history cursor advances, reset the cursor to the failed window before retrying it.

## Realtime order import

Shopify emits `ORDERS_CREATE` when an order is created and `ORDERS_UPDATED` when an order changes. Listening to the create event gives new orders a direct realtime path during high-volume order creation. EventBridge routes both event types to SQS, and `consume_ShopifyOrders_SQS` reads each queued message. HotWax Commerce uses the Shopify order identifier to request the current order data and then creates or updates the order.

When diagnosing realtime import, trace one Shopify order through the event, SQS delivery, the `consume_ShopifyOrders_SQS` consumer job run, and the Data Manager record with its `logId`, `createdByJobRunId`, `configId`, and terminal result, then confirm the matching OMS order. Realtime SQS import does not create a System Message. Do not use a history run or fallback batch as proof that the realtime path processed that order.

## Scheduled fallback import

The recurring shop-specific `queue_ShopifyOrderSync` job processes eligible order updates in scheduled batch windows. It is a recovery path for the realtime integration, not a substitute for the controlled pre-launch history import.

Review the job's **Active** state, Quartz schedule, queued system message, job run, tied import, and Data Manager result. Use **Run now** only for a controlled batch. For schedule operation and recovery, see [Manage Shopify Order Sync](https://github.com/hotwax/oms-documentation/tree/user-guides-pub/documents/system-admin/administration/company/manage-shopify-order-sync.md).

## Verify a downloaded order

Use the same Shopify order identifier throughout the check. Confirm the HotWax Commerce order has the intended Product Store, products and quantities, customer and addresses, sales channel, shipping method, payment method, and current status. For an existing HotWax Commerce order, confirm the flow updated the order without creating a duplicate.

For details about how Shopify fulfillment-order promises populate ship-group dates, see [Order promise dates](/documents/learn-shopify/shopify-reference/orders/order-promise-dates.md).

If an order is missing, first identify whether it belongs to history, realtime, or fallback processing. Then inspect that flow's earliest missing stage before rerunning work.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hotwax.co/documents/learn-shopify/shopify-reference/orders/order-download.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.