# Shopify Advanced Operations: Multi-Location Orders, Gift Cards & Payout Reconciliation ### 1. Overview This module ensures that **multi-location ecommerce operations, financial reconciliation, and liability tracking** are processed accurately and automatically within XoroERP. It enables seamless handling of: * Multi-location order splitting * Refund and return processing * Payment deposit linking * Gift card liability tracking * Payout synchronization and reconciliation The module provides structured financial and operational control for businesses operating Shopify stores with multiple fulfillment locations. *** ### 2. Functional Workflow #### 2.1 Multi-Location Order Splitting Workflow * A Shopify order containing items from multiple Shopify locations is created. * Shopify location data is transmitted with the order payload. * XoroERP evaluates configured Shopify ↔ Xoro location mappings. * The system splits the original Shopify order into separate Sales Orders — one per mapped Xoro store/location. * Each Sales Order generates its own invoice. * Invoice totals are proportionally allocated based on line-level distribution. **Result:** A single Shopify order may generate multiple Sales Orders and invoices in XoroERP. *** #### 2.2 Refund and Return Workflow * Refund or return is initiated in Shopify. * Refund payload includes store/location reference. * XoroERP identifies the associated split Sales Order. * Credit Memo is automatically generated against the corresponding invoice. * Financial and inventory effects are applied per mapped entity. Refund behavior mirrors the split order structure. *** #### 2.3 Deposit and Auto-Linking Workflow * Shopify payment is imported into XoroERP as a Deposit. * Deposit remains unapplied until shipment occurs. When the order is shipped: * Invoice is finalized. * Deposit is automatically linked to the invoice. * Invoice is marked paid. Deposit allocation follows location-based invoice splitting. *** #### 2.4 Gift Card Workflows **A. Purchase Gift Cards (Customer Purchase)** * Gift card purchased via Shopify order. * XoroERP creates a deposit entry. * Gift Card ID is stored and linked to the Sales Order. * Liability is recorded until redemption. **B. Issued Gift Cards (Merchant-Created)** * Gift card created directly in Shopify. * Gift card sync imports data independently. * Liability entry or credit memo created based on configuration. *** #### 2.5 Payout Synchronization Workflow * Payment gateway consolidates transactions into payout batches. * Payout records are synchronized into XoroERP. * Fees, disputes, rounding adjustments, and reserves are recorded using mapped accounts. * Bank reconciliation is performed against consolidated payouts. *** ### 3. Core Configuration Logic #### 3.1 Shopify ↔ Xoro Location Mapping | Shopify Element | XoroERP Mapping | | ----------------------------- | ---------------------------- | | Shopify Location | Xoro Store | | Shopify Location | Xoro Location | | Optional Fulfillment Location | Third-Party Location Mapping | A default mapping must exist to prevent import failures. **Incomplete mapping causes:** * Failed order splits * Incorrect invoice allocation * Refund posting errors *** #### 3.2 Split Order Enablement Rules * Enable only for multi-location merchants. * Do not enable for single-location operations. * Incorrect enablement causes financial fragmentation. *** #### 3.3 Gift Card Configuration Requirements * Gift Card ID is the primary linking identifier. | Setting | Purpose | | ---------------------------------- | ---------------------------- | | Gift Card SKU (Non-Inventory Item) | Represents gift card product | | Liability Account | Tracks unredeemed value | | Exchange Gift Card Account | Handles balance adjustments | | Auto-Fetch Missing Gift Cards | Imports historical data | | Import Before Integration Date | Prevents unpaid invoices | *** #### 3.4 Partial Gift Card Sync When an order includes both merchandise and gift cards: * Liability and revenue are allocated separately. * Prevents incorrect full-order classification. *** #### 3.5 Expiry Refund Configuration If enabled: * Expired or disabled gift cards automatically generate Credit Memos. * Liability balance is reduced automatically. *** #### 3.6 Payout Configuration Requirements Required configuration: * Integration start date * Bank account * Fee account * Dispute account * Rounding account * Reserve account (if applicable) * Currency selection Missing configuration prevents accurate reconciliation. *** ### 4. Transaction-Level Behavior #### 4.1 Split Order Creation * System reads Shopify location. * Generates separate Sales Orders per mapping. * Creates individual invoices. * Allocates revenue proportionally. *** #### 4.2 Refund Posting * Credit Memo created against correct invoice. * Financial reversal executed. * Inventory adjusted per mapped store. {% hint style="info" %} Incorrect mapping results in misposted refunds. {% endhint %} *** #### 4.3 Deposit Auto-Linking * Deposit automatically applied after shipment. * Invoice marked paid. * No manual payment entry required. *** #### 4.4 Gift Card Accounting Behavior **Purchase Gift Cards** * Deposit created * Liability credited * Linked using Gift Card ID **Issued Gift Cards** * Liability entry created directly * Independent of order workflow *** #### 4.5 Expired Gift Card Refund * Credit Memo generated automatically. * Liability adjusted. *** #### 4.6 Payout Consolidation System records: * Gross amount * Fees * Disputes * Net bank amount Supports streamlined bank reconciliation. *** ### 5. Examples **Example 1: Multi-Location Shopify Order** **Scenario:** Customer purchases items fulfilled from two locations.\ **System Impact:** * Two Sales Orders created * Two invoices generated * Revenue allocated by store *** **Example 2: Purchase Gift Card** **Scenario:** Customer purchases a $100 gift card.\ **System Impact:** * Deposit created * Liability credited * Revenue deferred *** **Example 3: Shipment Triggering Payment** **Scenario:** Prepaid order shipped.\ **System Impact:** * Invoice finalized * Deposit auto-applied * Invoice marked paid *** **Example 4: Daily Payout Import** **Scenario:** Gateway sends payout batch.\ **System Impact:** * Single payout record created * Fees recorded * Reconciliation simplified *** ### 6. Important Rules & Constraints * Do not enable split orders for single-location merchants. * Location mapping must be complete before import. * Gift Card ID is mandatory for linking liabilities. * Refunds rely on accurate location mapping. * Missing payout configuration causes reconciliation issues. *** ### 7. Best Practices * Conduct detailed client discovery before setup. * Document Shopify locations and third-party apps. * Validate split order behavior during testing. * Use deposit auto-linking instead of manual payment posting. * Confirm payment gateway configuration before payout setup. *** ### 8. Common Mistakes & Pitfalls | Mistake | Result | | ----------------------------------- | ----------------------------- | | Enabling split orders unnecessarily | Financial fragmentation | | Skipping location mapping | Refund and invoice misposting | | Failing to import gift cards | Unpaid invoices | | Ignoring third-party apps | Integration failures | | Manual payment posting | Reconciliation mismatch | | Incomplete payout setup | Bank discrepancies | *** ### 9. FAQ #### **FAQ 1: When should split orders be enabled?** Split orders should be enabled only when a business fulfills items from **multiple warehouses or locations**. When enabled, XoroERP automatically splits a single Shopify order into multiple orders based on fulfillment locations. This ensures that each warehouse processes only the items assigned to it. **What users should do:** * Enable this setting only if multiple fulfillment locations are actively used * Keep it disabled for single-location setups to avoid unnecessary order splitting **Location in XoroERP:**\ Integrations → Shopify → Order Settings → Enable Split Orders *** #### **FAQ 2: What happens if gift cards are not imported before go-live?** If existing gift cards are not imported before going live, invoices paid using those gift cards may appear as **unpaid in XoroERP**. This happens because the system cannot link the payment to a corresponding deposit (gift card record). **What users should do:** * Import all existing gift cards before go-live * Ensure proper mapping of gift cards as deposits **Location in XoroERP:**\ Integrations → Shopify → Financial Settings → Gift Card Import *** #### **FAQ 3: How are the purchase gift cards handled?** When a gift card is purchased, XoroERP records it as a **deposit (liability)** using the Gift Card ID. This ensures that: * Revenue is not recognized immediately * The amount is treated as a liability until redeemed **What users should do:** * Verify liability account mapping * Ensure gift card handling is correctly configured **Location in XoroERP:**\ Integrations → Shopify → Financial Settings → Gift Card Configuration *** #### **FAQ 4: How are issued gift cards processed?** Gift cards issued (e.g., store credit, refunds) are synced independently through configuration settings. They are tracked separately to ensure: * Proper visibility of store credits * Accurate customer balances **What users should do:** * Enable issued gift card sync * Monitor sync logs for accuracy **Location in XoroERP:**\ Integrations → Shopify → Gift Card Sync Settings *** #### **FAQ 5: What triggers automatic invoice payment?** Invoice payment is automatically triggered when **shipment is confirmed in XoroERP**. At this point: * The system links the deposit (payment) to the invoice * The invoice is marked as paid **What users should do:** * Ensure shipment is completed * Verify payment linkage after fulfillment **Location in XoroERP:**\ Integrations → Shopify → Payment Settings\ Inventory / Fulfillment → Shipment Confirmation *** #### **FAQ 6: Can payout synchronization be automated?** Yes, XoroERP supports **daily payout synchronization** from Shopify. This allows automatic tracking and reconciliation of Shopify payouts within the system. **What users should do:** * Enable payout sync * Review synced payout data regularly **Location in XoroERP:**\ Integrations → Shopify → Payout Settings → Enable Daily Sync *** ### 10. Conclusion A well-configured multi-location Shopify integration ensures accurate revenue allocation, reliable liability tracking, consistent refund processing, and streamlined bank reconciliation within XoroERP. Proper configuration of location mapping, gift card handling, deposit linking, and payout synchronization prevents financial discrepancies, operational errors, and reconciliation challenges across e-commerce operations. --- # Agent Instructions: 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/shopify-advanced-operations-multi-location-orders-gift-cards-and-payout-reconciliation.md?ask= ``` 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.