> 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

Reflect ESW-initiated appeasements (refunds or compensation) back into Shopify.

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="broken://spaces/69bGsllGv04t8wHIHruV/pages/87129aebd2293f4c97a2bd786b43a3faf3aa3011">Broken link</a></td></tr><tr><td>Order and Item-Level Cancellations</td><td><a href="broken://spaces/69bGsllGv04t8wHIHruV/pages/465a1bf0f89a80277189e786d587a8c0a0e877cf">Broken link</a></td></tr><tr><td>Shipping Address Update</td><td><a href="broken://spaces/69bGsllGv04t8wHIHruV/pages/c2f06d89166f7979ba488c174a09bf8dbc3b2849">Broken link</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 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/appeasements.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.