Match return data across the shop, ERP and payment system

When connecting a shop, ERP and payment provider, a return needs more than a shared “done” field. The integration must identify which line is coming back, what happens to stock and the state of the related refund. Define these relationships before implementing the interfaces.

Map a complete case

A fictional home accessories shop delivered two vases on order O-86 and received payment. One vase comes back with a chipped rim. In this example, a refund of 24 EUR has been agreed for that vase. The team plans the following mapping:

The link uses line and transaction references. Matching a product name or item code alone is insufficient when the same item occurs in several orders.

Define an internal integration model

The following record is a custom design for this fictional case, not a provider’s API call. Quantities refer to the return case; the amount is expressed in EUR cents.

{
  "returnId": "R-86",
  "orderReference": "O-86",
  "shopOrderLine": "OL-86-A",
  "shopFulfillmentLine": "FL-86-A",
  "erpDeliveryLine": "DL-86-A",
  "receivedQuantity": 1,
  "saleableStockDelta": 0,
  "refund": {
    "paymentReference": "PAY-86",
    "amountMinor": 2400,
    "currency": "EUR",
    "state": "requested"
  }
}

The references connect the shop order line, shop fulfillment line and original ERP delivery line to the payment. Also store the refund reference returned by the payment provider against the case. If the line cannot be identified unambiguously, the record should await clarification rather than be posted automatically through name matching.

Use the right source for each change

In this example, the shop supplies the link to the purchased line. The ERP confirms receipt, inspection outcome and stock release. The payment provider supplies the refund state. These responsibilities belong in the data contract; a different division of systems may require different ownership.

Shopify’s ReturnLineItem points to a Shopify fulfillment line; the integration must establish the link to the ERP line. Its Refund documentation explicitly notes that a record alone does not confirm a successful money movement. Stripe also describes separate events for creation, changes and failure. The integration needs to map the chosen provider’s actual states to its internal model.

A successful refund should therefore change only the payment state in this example. It does not make the damaged vase saleable. Equally, receiving the goods does not automatically make the refund successful.

Check the expected result

Check the case in an appropriate test environment: the partial return belongs to the correct line, the stock change remains 0 and 2400 cents belong to the correct payment. Once a successful refund is confirmed, its state changes while the goods remain blocked. An unclear payment response must remain visible as unresolved. A repeated status notification should update the same case. Technical handling of retries also requires a suitable idempotency strategy.

Sources

• Shopify — ReturnLineItem, GraphQL Admin API

• Shopify — Refund, GraphQL Admin API

• Stripe — Refund and cancel payments