integreat/docs/2026-08-15-remove-voided-orders-risk.md

---
title: remove-voided-orders can delete another client's payments
type: risk
date: 2026-08-15
status: open — decide before merging the re-key
---

# `remove-voided-orders` can delete another client's payments

Measured on the restored backup, 2026-08-15. This risk is **pre-existing** — nothing in the
sales-summary work created it — but it is live right now, and the re-key work touches the same
data, so it should be understood before merging.

## The mechanism, in four steps

**1. Charges are component entities of an order.**

```clojure
;; resources/schema.edn
{:db/ident :sales-order/charges
 :db/valueType :db.type/ref
 :db/isComponent true          ;; <- this is the load-bearing bit
 :db/cardinality :db.cardinality/many}
```

`:db/isComponent true` tells Datomic the charges *belong to* the order. It is what lets you
transact an order with its tenders nested inside, and it means the charges have no independent
existence as far as Datomic is concerned.

**2. `retractEntity` on a component parent deletes the children too.**

That is the documented behaviour of `:db/retractEntity`: it recursively retracts component
values. `square.core3/remove-voided-orders` ends with exactly that:

```clojure
(s/map (fn [[o]]
         [[:db/retractEntity [:sales-order/external-id (:sales-order/external-id o)]]]))
```

It asks Square for the last 10 days of orders, keeps the ones that should *not* be imported —
voided and cancelled orders — and retracts any of those we already stored. That is correct and
desirable on its own: a voided order should not sit in the books.

**3. But one charge can be shared by two orders.**

When two clients are configured on the same Square location, both import the same Square data.
Order keys embed the client, so each client gets its own order entity. Charge keys did **not**
embed the client, and `:charge/external-id` is `:db.unique/identity`, so both clients' orders
resolved to *the same charge entity*:

```
NGCD order 17592395490523 ──┐
                            ├──> charge 17592490524   ← one entity, two parents
NGCC order 17592395511722 ──┘
```

**4. So retracting one order deletes a charge the other order still points at.**

Datomic sees a component and removes it. The surviving order keeps its line items — its sales —
but its tender is gone. The day then shows revenue with no payment against it, the summary goes
out of balance, and the payment is gone from the current database value. (History retains it, so
it is recoverable by someone who knows to look, but nothing in the app will show it again.)

## How exposed are we

Measured over the 10 contended clients across 2026-07-13 → 08-14:

| | |
|---|---|
| Charges examined | 56,829 |
| **Referenced by more than one order** | **35,870 (63%)** |

So this is not a theoretical corner. Roughly two thirds of the charges in that population have
two parents, and any voided order among them takes a charge down with it.

The exposure window for *new* damage is the rolling 10 days `remove-voided-orders` searches, but
the shared charges themselves span the whole period the locations were double-configured.

## What changes after Phase 0 and the re-key, and what doesn't

- **Phase 0 (done on the restore)** stops new sharing: only one client per location imports now,
  so no new order pairs form.
- **The re-key (done for refunds and the contended clients' charges)** makes sharing structurally
  impossible going forward, because a charge key now contains the client code.
- **Neither retroactively splits the 35,870 charges that are already shared.** They still have two
  parents. Until they are split, `remove-voided-orders` remains capable of deleting a payment
  belonging to the other client.

This is why plan §3.3 forbids retracting anything — including any historical cleanup of the
duplicate clients' data — until a verification query shows zero charges with more than one parent.

## Options, roughly in order of preference

1. **Split the shared charges, then let removal run normally.** Re-import the affected window now
   that keys are client-scoped, so each client creates its own charge entity. This reuses the
   import path rather than hand-constructing component entities. Verify with a query for charges
   having more than one referencing order; it must reach zero.

2. **Guard the retraction.** Before retracting an order, check whether any of its charges are
   referenced by another order; detach those (retract the `:sales-order/charges` ref rather than
   the charge) and retract the rest. Small, contained change, and it makes the operation safe
   regardless of what shape the data is in — worth doing on its own merits even after a split.

3. **Do nothing and accept it.** Only defensible once every location has a single client *and*
   the historical shared charges are gone. Not true today.

## What I did about it during the validation run

I ran the import on the restore with `remove-voided-orders` **skipped**, and ran the other steps
(`upsert-locations`, `upsert`, `upsert-payouts`, `upsert-refunds`) normally. That kept the
validation faithful to how the import behaves without risking silent payment loss in the data
the measurements were about to be taken from.

**Nothing in the production system has been changed.** This note is about a risk that already
exists there.