> 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/appeasements.md).

# Appeasements

Sync appeasements between ESW and Shopify.

ESW can issue refunds or compensation after order import.

Mirror that financial state in Shopify to keep reporting aligned.

### Prerequisites

* You can receive appeasement events from ESW.
  * Webhook, message bus, or scheduled polling.
* You can call the Shopify Admin API (REST/GraphQL).
* You have a stable mapping between:
  * ESW order reference
  * Shopify order id / name
* You’ve defined your Shopify representation of appeasements.
  * Refund against line items.
  * Refund at order level.
  * Non-item compensation (gift card or custom item).

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

### ESW-driven appeasement flow

{% stepper %}
{% step %}

### Capture appeasements in ESW

Listen for ESW appeasement activity at:

* Order level
* Item level

Capture these fields at minimum:

* ESW order reference
* Appeasement id (or another unique event id)
* Amount and currency
* Affected items and quantities (if item-level)
* Reason code / notes
* Timestamp
  {% endstep %}

{% step %}

### Normalize and validate the event

Before updating Shopify:

* Confirm the order exists in Shopify.
* Confirm currency matches the Shopify order currency.
* Confirm the appeasement is allowed for the order state.
  * Example: don’t refund beyond captured/paid totals.
* Deduplicate by appeasement id.
  {% endstep %}

{% step %}

### Map the appeasement to a Shopify action

Decide the Shopify primitive you will use:

* **Refund** for money back to the shopper.
* **Adjustment** or custom line for non-item compensation.

Keep the mapping deterministic.

The same ESW appeasement should always produce the same Shopify mutation.
{% endstep %}

{% step %}

### Apply the update in Shopify

Create the corresponding refund or adjustment in Shopify.

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

Recommended behavior:

* Store the Shopify refund id you created.
* Retry transient failures.
* Stop and alert on validation errors.
  {% endstep %}

{% step %}

### Reconcile and monitor

Track and alert on:

* Shopify updates that fail or time out
* Mismatched totals between ESW and Shopify
* Duplicate events that would trigger double refunds

Add a daily job to reconcile recent appeasements if needed.
{% endstep %}
{% endstepper %}

### Related topics

<table data-view="cards"><thead><tr><th>Topic</th><th data-card-target data-type="content-ref">Link</th></tr></thead><tbody><tr><td>Order Management</td><td><a href="/spaces/69bGsllGv04t8wHIHruV/pages/87129aebd2293f4c97a2bd786b43a3faf3aa3011">/spaces/69bGsllGv04t8wHIHruV/pages/87129aebd2293f4c97a2bd786b43a3faf3aa3011</a></td></tr><tr><td>Order and Item-Level Cancellations</td><td><a href="/spaces/69bGsllGv04t8wHIHruV/pages/465a1bf0f89a80277189e786d587a8c0a0e877cf">/spaces/69bGsllGv04t8wHIHruV/pages/465a1bf0f89a80277189e786d587a8c0a0e877cf</a></td></tr><tr><td>Shipping Address Update</td><td><a href="/spaces/69bGsllGv04t8wHIHruV/pages/c2f06d89166f7979ba488c174a09bf8dbc3b2849">/spaces/69bGsllGv04t8wHIHruV/pages/c2f06d89166f7979ba488c174a09bf8dbc3b2849</a></td></tr></tbody></table>


---

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