> 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/shopify/shopify-native/integration/order-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.