Part 3: The Order Status State Machine — Making Sense of the Madness

By now, we’d built a fortress that could handle uploads, chunk huge files, and keep servers alive. But reconciliation isn’t just about data volume — it’s about meaningful data. And that means wrestling with the tangled web of order statuses, commission tweaks, and all the exceptions that come with real-world sales.

Orders: More Than Just Numbers

To someone with no eCommerce experience, at first glance, an order looks simple: buyer clicks, creator gets commission, brand gets paid. But in reality, each order is a living, breathing entity with multiple possible states and twists. Add a layer of affiliate on top of it with 1 additional entity getting commission and you find yourself with an enormous number of cases. Remember, each order has multiple items, and each item has its own lifecycle!

Handling these states correctly is mission-critical. Show the wrong status to creators, and you risk confusion, mistrust, and angry support messages.

Enter the State Machine: Order Status, Meet Order Logic

To bring order (pun intended) to the maze of reconciliation, we introduced a state machine — a well-defined system that governed how an order could move from one status to another. More importantly, it also defined how an order couldn’t move.

No more manual mishaps, accidental overwrites, or mystery transitions. Every order followed a tightly controlled progression backed by business rules and logic.

Here’s how it worked:

An order started in a pending state.
After a file was uploaded and validated, it moved to a synced state.
Post manual QC and approval, it transitioned to manually reconciled.
Only after final checks did it move to confirm, making it eligible for payout and visibility to the creator.

But beyond guiding the flow, the real superpower of the state machine was what it prevented.

Let’s say a brand accidentally re-sent the same order in the next cycle — it happened more often than you’d think.
Without guardrails, that order might get reprocessed, paid out twice, or flagged incorrectly.
But the state machine stepped in and said:

“This order is already confirmed (though it might not be in confirmed state, but state machine says its confirmed by brand earlier). No need to touch it again.”

That one safeguard saved us from duplicate payouts for orders, unnecessary escalations, and hours of manual cleanup. It gave us auditability, confidence, and consistency across cycles.

Entry Types: Tracking the Story Behind Every Sale

Every line item in our system had an entry type to explain why it was there. Types included:

Sale: The original sale.
Return: Returned items, creating negative entries.
Cancellation: Orders canceled before delivery.
Fraud: Suspicious sales flagged manually.
Adjustment: Corrections due to mismatches or commission changes.
Backfill: Historical fixes.
Others: Miscellaneous cases.
Sale Not Found: When brands reported sales we didn’t have (cue raised eyebrows).

This granular tracking was key to untangling complex scenarios, like partial returns or commission changes mid-cycle.

Real-World Hurdles — Adjustments and Commission Twists

Remember when we talked about commission structures being madness? Let’s go a level deeper.

At scale, it wasn’t just about whether a sale was confirmed or returned. We were dealing with changing prices, shifting seller-level commissions, creator account issues, and late brand instructions — all of which made accurate reconciliation a moving target.

Let’s start with a basic scenario:

Let’s start simple.

🧾 The Order Example:

An order is captured at ₹1,000.
Later, during reconciliation, the brand reports the actual transaction was ₹1,200.

Sounds easy? Not quite. Instead of just adding a delta of ₹200, we created two adjustment entries:

One reversing the original: -₹1,000
One replacing it with the corrected amount: +₹1,200

This way, the system had a full audit trail of what changed and why.

And it wasn’t just about price. We also tracked status entries alongside value changes:

Delivered: ₹0 entry, status = “Delivered”
Returned: -₹1,200 entry, status = “Returned”

👉 Why not just store the net result? Because we needed to preserve the entire GMV trail and the reason for every change. That’s where entry types came in.

Because we needed to preserve the full GMV trail and reason for change.
That’s where entry types came in — sale, return, adjustment, commission-correction, etc.

But what about commissions?

That’s where it got tricky overtime. Here’s why commission adjustments happened:

📉 Delayed Brand Updates

We might capture a sale at 15%, only for the brand to later report it should be 5%.
➝ Result: a -₹100 commission adjustment, even though the order wasn’t returned.

🚫 Creator Account Deletion

A creator’s account gets deleted mid-month.
Orders placed before deletion still exist, but their commission becomes ineligible.

🔀 Platform Mapping Issues

Telegram creators, Instagram creators, and others often had different commission structures.
Orders had to reflect the correct platform mapping for payouts.

🛒 Bucket-Based Commission Logic

Commission varied by category (beauty, fashion, electronics) and by seller (retail vs. marketplace).
If either changed post-capture → the commission had to be recalculated.

Over time, we bucketed these variations into five core adjustment types — price, category-based, seller-based, and their combinations (price × category, price × seller). That structure gave us consistency without losing flexibility.

In theory, it sounds like a one-off exception.
In practice, this was a recurring pattern across brands, with different combinations of price, commission, and account logic every week.

Rather than chase perfection upfront, we built a flexible adjustment system that embraced the chaos. This gave us auditability, consistency, and breathing room to continue improving the upstream systems — without breaking reconciliation downstream.

Synchronizing Staging and Production: Showing Data with Confidence

Data flowed from staging tables to production only after passing validations and status transitions.

Once synced, order status updated to Manual reconciliation confirmed.
After further checks, status moved to Confirmed.
Only then did payouts get generated.

Separating syncing from showing ensured creators never saw half-baked or incorrect data.

After Every Month end cycle — us:

Wrapping Up Part 3

The order status state machine and entry types brought much-needed discipline to the wild world of reconciliation data. They helped us manage complex business rules, minimize errors, and keep creators’ trust intact.

Next up: the exciting (and sometimes frustrating) journey into automated reconciliation, brand integrations, and the reality check that followed.

Stay tuned. The saga continues.