Skip to main content
Returns are where two systems drift apart most quietly. A refund lands in Shopify, the return is booked in HotWax a little later, and drafts, cancellations, and in-transit items all look like gaps if you compare naively. Darpan’s returns and exchange checks are built to report only the gaps that are real, and to say what they left out. There are two checks:
  • Returns: every Shopify refund or return in the window has a matching HotWax return, and the other way round.
  • Exchanges: every closed Shopify exchange in the window was imported into HotWax as an exchange order. This runs inside an orders run.

​
Before you start

Confirm:
  • A Shopify connection with Returns enabled, and a token that can read returns. See Set up Shopify.
  • A HotWax connection with Refunded returns or Returns enabled for returns, and Orders for exchanges. See Set up HotWax.

​
Set up a returns run

Create the run as in Set up a reconciliation run, with both sides as API sources: Shopify returns emits one record per refund or return event, keyed by the Shopify refund ID or return ID. HotWax books each return under the same ID as its externalId, so the two sides match one-to-one. On the HotWax side the key card offers Shopify return ID and Refund or return ID.

​
Choose the HotWax returns source

The two carry the same fields, so moving a run from one to the other is a source switch.

​
Leave in-progress returns out

A Shopify return that has not finished usually has no HotWax return yet. On the Shopify side, add an exclusion on Return status with the value IN_PROGRESS. This is Shopify’s own order return status, so it describes the whole order: excluding IN_PROGRESS drops an in-progress order’s refund rows as well as its return. See Leave records out with exclusions.
Before 2.0.0 this exclusion used a Return workflow status field with REQUESTED and OPEN. That field is withdrawn, and a rule saved on it matches nothing. Re-add the rule on Return status with IN_PROGRESS.

​
What a returns run does not report

Several kinds of one-sided record are expected, not gaps. Darpan removes them before the result is written and says how many it removed. Records still reported missing in HotWax are then checked one by one with a point lookup, by both externalId and shopifyReturnId. Records found that way are dropped. See Verification passes.
A rule only removes a record when the record’s own data proves it. Where the evidence is incomplete, the record stays reported.

​
Exchanges

An exchange in Shopify becomes a separate exchange order in HotWax, carrying the same Shopify order ID as the original. Order extracts from HotWax leave exchange orders out by default, so they do not show up as extra orders in an orders run. When an orders run compares Shopify orders with the HotWax Orders endpoint, Darpan also runs an exchange presence check:
  1. It lists the Shopify exchanges created in the run window.
  2. It matches them against the exchange orders HotWax returned in the extract.
  3. For any left over, it asks HotWax directly by order ID.
  4. Only exchanges HotWax confirms it does not have are reported, as missing from HotWax.
Each run looks up at most 200 exchanges in HotWax. Any beyond that are deferred to a later run rather than reported, and the run note says how many.

​
Reading the result

The run note on a returns or exchange run lists what each rule removed, and how many exchanges were matched, pending, or in transit. A count that moved between runs can be traced to these numbers rather than guessed at. When a record is reported:
  • Missing from HotWax: the refund, return, or exchange was not imported. Check the HotWax import for that order.
  • Missing from Shopify: HotWax holds a return that Shopify does not list in the window. Check the return’s dates first; a return near the window edge may belong to the next window.

​
Next step

Schedule the run in Set up an automation. Scheduled runs apply the same checks as a manual run.