5 min read13 views

Soft Delete Inventory Bug — Phantom Serial Stock After Purchase Delete

Soft-deleting a purchase looked fine until serial-tracked products stayed sellable. The movement ran, quantity didn’t move, and serials were never detached.

laravelinventorysoft-deleteserial-numbersstock-movementssaas
Soft Delete Inventory Bug — Phantom Serial Stock After Purchase Delete

Quick Answer

A soft delete inventory bug is when the purchase row gets deleted_at but sellable stock does not reverse. On serial-tracked products, quantity usually comes from in_stock serial rows. If delete only posts a stock movement and skips serial detach, those serials stay sellable — classic phantom inventory.

Quick Facts

ItemDetails
TopicSoft delete inventory bug (phantom serial stock)
CategoryLaravel / Inventory / Multi-tenant SaaS

What Is a Soft Delete Inventory Bug?

Soft delete hides a document with deleted_at. Inventory soft delete also has to undo what that document did to stock.

This is not “forgot to soft-delete line items.” The purchase can disappear from the list while serial numbers stay in_stock. Non-serial SKUs often reverse with a negative movement. Serial SKUs usually need a second step: detach or void those serials, then sync quantity from what remains.

Why It Matters

  • Phantom stock — deleted inbound goods still look available; POS and invoices sell units you do not have.
  • Quiet audit — a movement can say “Purchase stock restored” with quantity_change = 0 while serials never moved.
  • Path drift — update may detach serials; delete may not. Same domain event, different cleanup. That is how the bug survives review.

How It Works

With track_serials, many Laravel inventory apps split ownership: movements stay for audit, but sellable quantity is the count of in-stock serials. Purchase-type movements often force change = 0 for those products so you do not double-count. That only works if delete also tears down the serials.

flowchart TD
  A[Soft-delete purchase] --> B[restoreStock movement]
  B --> C{track_serials}
  C -->|no| D[Quantity decreases]
  C -->|yes| E[change forced to 0]
  E --> F[Serials still in_stock]
  F --> G[Phantom sellable stock]
  A -.-> H[detachPurchase + sync]
  H --> I[Qty matches reality]

  classDef step fill:#1e3a5f,stroke:#38bdf8,color:#e0f2fe
  classDef warn fill:#7f1d1d,stroke:#f87171,color:#fecaca
  classDef ok fill:#14532d,stroke:#4ade80,color:#dcfce7
  classDef gate fill:#422006,stroke:#fbbf24,color:#fef3c7

  class A,B,D step
  class C gate
  class E,F,G warn
  class H,I ok
Blue = normal path. Gold = serial gate. Red = bug when detach is skipped. Green = fix.
  1. Document delete — authorize, skip purchases with returns, soft-delete the header.
  2. Stock reverse — restoreStock() records a negative purchase movement per line.
  3. Serial bypass — for track_serials, purchase movements may zero the quantity change on purpose.
  4. Required cleanup — detach purchase serials and sync quantity inside the same transaction. Update already does this; delete must too.

Step-by-Step Guide

Step 1: Map every path that undoes a purchase

Write a table: create, update, soft-delete, restore, purchase-return. Two columns per path — quantity movement, serial mutation. Done when every undo path has both, or a written reason serials stay untouched.

Step 2: Reuse the update cleanup on delete

If update already runs restoreStock() then detachPurchase before replacing lines, delete should call the same helper while item IDs are still loaded.

DB::transaction(function () use ($purchase, $purchaseService) {
    $purchase->load('items');
    $purchaseService->restoreStock($purchase);
    (new ProductSerialService)->detachPurchase($purchase->items);
    $purchase->delete();
});

Skip detach and serial products keep in_stock rows. The movement may still insert with a zero change — easy to miss in logs.

Step 3: Prove it with a serial fixture

Product with track_serials = true, purchase 2 serials, confirm quantity = 2. Soft-delete the purchase. Done looks like: deleted_at set, those serials gone or not sellable, quantity = 0. Run restore once and confirm you do not invent extra stock.

Real-World Example

Stack: Laravel API + Nuxt SPA inventory SaaS. Purchase update restored stock and called detachPurchase() before force-deleting old items. Purchase delete only called restoreStock().

StockMovementService treats purchase as a serialized bypass type — for tracked products it zeroes the change so quantity is not double-managed. Correct when serials are the source of truth. On delete, nobody removed the serials. Shop UI still showed those SNs after the purchase vanished from the list.

Fix: same detach + sync as update, keep the movement for audit, and stop returning blanket “deleted successfully” when some UUIDs were skipped for returns. Add a feature test that asserts serial count and product quantity after soft-delete.

Pros & Cons

Advantages

  • Serial-as-source-of-truth avoids double-counting when create, sale, and update all go through serial services.
  • Soft delete keeps the document for audit and restore instead of hard-wiping history.
  • One shared undo helper keeps update and delete from drifting again.

Disadvantages

  • Bypass + soft-delete is easy to half-ship: movement looks done, stock is not.
  • Restoring a soft-deleted purchase must re-attach serials carefully or you flip the bug.
  • Returns need honest API responses — silent continue hides failed cleanup.

Best Practices

  • Put serial detach in the same DB transaction as document soft-delete.
  • One “undo purchase stock” helper for update, delete, and return — do not copy half of it.
  • Assert both stock_movements and serial in_stock counts; a zero-change movement alone is not green.
  • Return 422 or a partial-failure list when returns block delete.
  • Document which movement types bypass quantity and which service owns serial lifecycle.

Common Mistakes

  • Only restoreStock on delete — update already felt complete. Fix: call the same detach helper.
  • Trusting movements as qty truth for serial SKUs — audit row exists. Fix: quantity = count of in-stock serials after mutations.
  • Testing delete only with non-serial products — bypass never fires. Fix: one track_serials fixture on every reverse path.
  • Success after skipping returned purchases — loop continues. Fix: list blocked UUIDs or fail the request.

Frequently Asked Questions

What is a soft delete inventory bug?

Soft-deleting a purchase, invoice, or adjustment leaves product quantity or serial availability inconsistent with the removed document — usually because quantity math and serial lifecycle were not both reversed.

How do I fix phantom stock after deleting a purchase?

In the same transaction: post the reverse movement for audit, detach or void the purchase serials, sync product quantity from remaining in-stock serials. Match the update path.

Soft delete vs hard delete for inventory documents?

Soft delete wins for audit and undo when stock and serials reverse cleanly. Hard delete without a ledger is worse. Prefer soft delete plus reversible stock services.

Is serial tracking worth the extra delete complexity?

Yes for phones, appliances, and warranty-heavy SKUs — every create/update/delete/return must touch serials. For bulk commodity stock, leave track_serials off and use plain quantity movements.

Summary

Soft-deleting a purchase is more than deleted_at. For serial products a purchase movement may intentionally change quantity by zero — serials own the count. Miss detach on delete and you get phantom sellable stock while the UI says the purchase is gone. Mirror update cleanup, test with serial fixtures, and make skipped deletes visible in the API.

Key Takeaways

  • Soft delete of inventory documents must reverse stock side effects, not only hide the header.
  • When serials drive quantity, a zero-change movement without detach leaves phantom stock.
  • Update and delete must share the same undo helper; asymmetric paths are the usual root cause.
  • Feature tests need a track_serials case on every reverse path or the bug stays invisible.
  • Do not report full success if some purchases were skipped for returns or authorization.

Keep learning — next reads from the same topics.

Discussion

Comments

0 comments · new ones appear after approval

No comments yet. Be the first to share your thoughts.

Leave a comment

Your comment will be reviewed before it appears.