> For the complete documentation index, see [llms.txt](https://docs.xorosoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xorosoft.com/xoroerp-1/connected-apps/xoro-shopify-implementation-deep-dive/managing-orders-refunds-and-exchanges-in-xoroerp/order-sync-refund-control-and-inventory-lifecycle-management.md).

# Order Sync, Refund Control & Inventory Lifecycle Management

### 1. Overview

This document manages the end-to-end synchronization of Shopify transactions within XoroERP. It governs order import behavior, refund processing workflows, inventory adjustments, and financial document generation to ensure consistent data flow between Shopify and XoroERP.

***

### 2. Functional Workflow

#### 2.1 Order Import Workflow

* Shopify is configured as an active sales channel.
* Orders created in Shopify are automatically fetched by XoroERP.
* Orders enter a pending import state before being processed sequentially.
* XoroERP validates order data and creates corresponding Sales Orders.
* Inventory, customer, and financial mappings are applied.
* Orders progress through the fulfillment lifecycle within XoroERP.

***

#### 2.2 Synchronization Behavior

* Synchronization runs automatically at regular intervals.
* Orders are retrieved in batches but processed individually.
* Updates made in Shopify trigger automatic synchronization updates in XoroERP.

***

#### 2.3 Refund Workflow

* Refunds are initiated in Shopify.
* Shopify transmits refund details to XoroERP.
* XoroERP evaluates:
  * refund type
  * restocking flag
  * current sales order status
* The system generates inventory and/or financial documents accordingly.

***

### 3. Core Configuration Logic

#### 3.1 Integration Date Configuration

The integration date determines the earliest Shopify orders eligible for import.

* Orders prior to this date are excluded.
* Incorrect configuration may result in missing historical data or unintended imports.

***

#### **3.2 Sync Scheduling**

| Parameter       | Behavior                                          |
| --------------- | ------------------------------------------------- |
| Sync Frequency  | Controls how often orders and updates are fetched |
| Processing Mode | Sequential validation ensures data integrity      |
| System Load     | Higher frequency increases processing demand      |

***

#### 3.3 Order Identification Structure

XoroERP uses multiple identifiers to ensure traceability.

| Field                        | Purpose                                           |
| ---------------------------- | ------------------------------------------------- |
| Source                       | Identifies originating Shopify store              |
| Reference Number             | Shopify-visible order number                      |
| Third-Party Reference Number | Backend transaction identifier for reconciliation |

{% hint style="info" %}
**Order numbers** are not guaranteed to be unique across multiple Shopify stores. Source-level identification must always be validated.
{% endhint %}

***

#### 3.4 Source of Transactional Updates

Shopify is the point where ecommerce transactions such as orders, cancellations, and refunds are initiated.

XoroERP automatically reflects these updates to manage fulfillment, inventory, and accounting processes. To maintain synchronization accuracy, any changes to Shopify-originated transactions should be performed in Shopify.

***

### 4. Transaction-Level Behavior

#### 4.1 Sales Order Lifecycle Statuses

* System automation evaluates the current status before applying updates.

| Status             | Description                       | Behavior During Sync                 |
| ------------------ | --------------------------------- | ------------------------------------ |
| Released           | Order allocated but not fulfilled | Refunds may create adjustments       |
| Waived             | Allocation removed                | System may void and recreate waves   |
| Shipped (Invoiced) | Order fulfilled and invoiced      | Refunds generate financial documents |

***

#### 4.2 Refund Processing Logic

Refund behavior is determined by:

* refund type
* restocking selection

***

#### 4.3 Refund Types

| Refund Type       | Inventory Impact | Financial Impact |
| ----------------- | ---------------- | ---------------- |
| Quantity Only     | Yes              | No               |
| Amount Only       | No               | Yes              |
| Quantity + Amount | Yes              | Yes              |

***

#### 4.4 Restocking Behavior

* Restocking directly affects Available-to-Sell (ATS) calculations.

| Restocking Option | Result                                       |
| ----------------- | -------------------------------------------- |
| Restock Enabled   | Inventory returned to available stock        |
| Restock Disabled  | Inventory permanently removed via adjustment |

***

#### 4.5 Document Generation Rules

* **Inventory Credit Memo (ICM)** reflects both inventory and financial implications.
* **Credit Memo** reflects financial impact only.

| Scenario             | Document Created                        |
| -------------------- | --------------------------------------- |
| Quantity-only refund | Zero-amount Inventory Credit Memo (ICM) |
| Amount-only refund   | Credit Memo                             |
| Combined refund      | ICM with financial impact               |

***

#### 4.6 Inventory Calculations

* Available-to-Sell (ATS) is calculated as:

```
ATS = Available Inventory – Released Quantities
```

***

### 5. Examples

**Example 1: Quantity-Only Refund with Restocking**

**Scenario:** Customer returns two units without monetary refund.

**System Impact:**

* Inventory added back to available stock
* Zero-amount ICM generated
* No financial refund recorded
* ATS recalculated

***

**Example 2: Amount-Only Refund After Shipment**

**Scenario:** Customer receives a partial monetary refund without returning goods.

**System Impact:**

* Credit Memo generated
* No inventory movement
* Financial adjustment recorded
* Inventory remains unchanged

***

**Example 3: Combined Refund for Shipped Order**

**Scenario:** Customer returns goods and receives payment refund.

**System Impact:**

* ICM generated with quantity and value
* Inventory returned to stock (if restocked)
* Financial refund recorded
* Order financials updated

***

### 6. Important Rules & Constraints

* All refunds must originate in Shopify; XoroERP does not initiate refund transactions.
* Sales order status determines how synchronization updates are processed.
* Order numbers cannot be assumed unique; always validate source context.
* Integration date strictly controls which historical orders are imported.
* Manual edits to Shopify-originated orders in XoroERP are overwritten by sync.
* Restocking selection dictates whether inventory is returned or adjusted out.
* Large import volumes may take time to fully appear as synchronization completes.

***

### 7. Best Practices

* Always validate integration using test orders before enabling production synchronization.
* Educate users to perform all order edits directly in Shopify.
* Use source-based filtering when troubleshooting duplicate order numbers.
* Monitor refund types carefully to anticipate inventory and accounting impact.
* Validate ATS recalculations after refund scenarios to ensure stock accuracy.

***

### 8. Common Mistakes / Pitfalls

| Situation                               | Result                                  |
| --------------------------------------- | --------------------------------------- |
| Editing Shopify orders inside XoroERP   | Changes overwritten during sync         |
| Ignoring source while searching orders  | Duplicate order confusion               |
| Incorrect integration date              | Missing or excessive historical imports |
| Selecting no-restocking unintentionally | Permanent inventory reduction           |
| Misinterpreting refund type             | Incorrect document generation           |

***

### 9. Frequently Asked Questions (FAQ)

#### **Where should refunds for Shopify orders be processed?**

Refunds must always be processed in **Shopify (Shopify Admin → Orders → Refund)**.

In XoroERP, Shopify acts as the **source of truth for all order transactions**, including refunds. Once the refund is processed in Shopify, XoroERP will automatically sync and create the required financial and inventory records.

**What to do:**

* Always initiate refunds in Shopify
* Allow the system to sync the update into XoroERP
* Avoid creating manual refund entries in XoroERP, as this can lead to mismatches

***

#### **Can quantities or pricing be edited in XoroERP for Shopify orders?**

No, quantities and pricing for Shopify orders should not be edited in XoroERP.

Shopify controls the order data, and any manual changes made in XoroERP will be **overwritten during the next sync**.

**What to do:**

* Make all order changes (quantity, price, discounts) directly in Shopify
* Allow XoroERP to sync the updated order
* Avoid manual edits in XoroERP to prevent data inconsistencies

***

#### **What happens when restocking is enabled during a refund?**

When restocking is enabled in Shopify during a refund:

* The returned items are added back to inventory
* XoroERP updates the stock accordingly
* ATS (Available to Sell) is recalculated

**What to do:**

* Enable restocking if the returned items are **resellable**
* Verify inventory levels in XoroERP after sync
* Use this option to maintain accurate stock for future sales

***

#### **What happens when restocking is disabled during a refund?**

When restocking is disabled:

* The returned items are **not added back to inventory**
* XoroERP processes it as an **inventory adjustment**
* Stock is removed from sellable inventory

**What to do:**

* Disable restocking if items are damaged, lost, or not resellable
* Do not expect inventory to increase after refund
* Review inventory adjustments in XoroERP if needed

***

#### **Why are duplicate order numbers visible in XoroERP?**

Duplicate order numbers can appear when **multiple Shopify stores or sources** are connected, as different stores may generate the same order numbers.

**What to do:**

* Use **store name or source identifier** to differentiate orders
* Avoid relying only on order number when searching or reconciling
* Filter or group orders by store for clarity

***

#### **What document is created when a shipped Shopify order is refunded?**

When a shipped order is refunded, XoroERP automatically creates:

* **Inventory Credit Memo** (if inventory is involved)
* **Credit Memo** (if it is a financial-only refund)

This depends on how the refund is processed in Shopify.

**What to do:**

* Review the generated document under:
  * Sales → Credit Memo / Inventory Credit Memo
* Verify:
  * Inventory impact (if applicable)
  * Financial adjustments
* Ensure the document aligns with the refund processed in Shopify

***

### **Key Reminder for Users**

* Shopify controls order and refund actions
* XoroERP reflects and processes synced data
* Always perform operational changes in Shopify, not XoroERP

***

### 10. Conclusion

The Shopify Integration module establishes a reliable synchronization framework between Shopify and XoroERP by controlling order import behavior, refund processing, and inventory adjustments. Proper configuration of integration settings, refund workflows, and synchronization rules ensures accurate financial reconciliation, consistent inventory tracking, and seamless ecommerce operations.

By maintaining Shopify as the transaction source, validating integration parameters, and aligning restocking decisions with operational processes, organizations can prevent data inconsistencies, reduce manual intervention, and achieve scalable ecommerce fulfillment within XoroERP.


---

# 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:

```
GET https://docs.xorosoft.com/xoroerp-1/connected-apps/xoro-shopify-implementation-deep-dive/managing-orders-refunds-and-exchanges-in-xoroerp/order-sync-refund-control-and-inventory-lifecycle-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.