> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/shopify/shopify-native/integration/order-management.md).

# Order Management

Sync orders, fulfillment, and cancellations between Shopify and ESW.

Shopify sends order events via webhooks.

Your integration posts orders to ESW.

ESW fulfillment updates flow back to Shopify.

### Prerequisites

* You have an integration service that can receive Shopify webhooks.
* You have access to:
  * Shopify Admin API (REST/GraphQL)
  * ESW Order APIs for order import and updates
* You’ve decided which system “owns” downstream changes:
  * Cancellations
  * Partial cancellations (item-level)
  * Fulfillment and tracking

{% hint style="info" %}
Treat all inbound events as at-least-once delivery.
{% endhint %}

### Webhook-driven order flow

{% stepper %}
{% step %}

### Subscribe to Shopify order webhooks

Create webhook subscriptions for the topics you support.

Common topics:

* `orders/create`
* `orders/updated`
* `orders/cancelled`

#### Shopify <i class="fa-webhook" style="color:$primary;">:webhook:</i> : [Webhooks](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook).

{% endstep %}

{% step %}

### Receive and validate the webhook

When a webhook fires:

* Verify the request is from Shopify (HMAC validation).
* Deduplicate on webhook id / event id.
* Enrich the payload if you need full order detail.
  {% endstep %}

{% step %}

### Import the order into ESW

Map Shopify order data to the ESW order model.

Then submit the order to ESW as an **offline order** (or your ESW-required type).

Typical mapping considerations:

* Order id, timestamps, and customer identifiers
* Line items (variant id / SKU), quantities, discounts
* Shipping method and costs
* Taxes and duty handling (based on your ESW setup)
  {% endstep %}

{% step %}

### Apply ESW fulfillment updates back to Shopify

When ESW creates shipments or updates fulfillment status:

* Capture ESW shipment/tracking events.
* Update the Shopify fulfillment with:
  * Tracking number(s)
  * Carrier
  * Fulfillment status

#### Shopify reference <i class="fa-code" style="color:$primary;">:code:</i> : [fulfillmentCreateV2](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCreateV2).

{% endstep %}

{% step %}

### Synchronize cancellations and item-level changes

Decide which events you propagate and when.

Typical approaches:

* Shopify cancellation triggers ESW cancellation.
* ESW cancellation triggers Shopify cancellation or adjustments.

#### Shopify <i class="fa-webhook" style="color:$primary;">:webhook:</i>:

* [orders/cancelled webhook](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-cancelled)
* [orders/updated webhook](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-updated)
  {% endstep %}

{% step %}

### Reconcile and monitor

Add a daily job to catch missed events.

Track and alert on:

* Orders not imported to ESW
* Fulfillment updates failing to write to Shopify
* Repeated webhook retries / throttling
  {% endstep %}
  {% endstepper %}


---

# 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://developer.esw.com/shopify/shopify-native/integration/order-management.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.