How Edit Sessions Work
A session is the unit we count, log, and email about. Most merchants never need to know what a session is — but if you want to understand the timing in your activity log or email cadence, this is the page.
The rule
A session is all actions on the same order by the same customer within 5 minutes of the first save.
The 5-minute window is fixed — it starts when the customer first saves something, and it does not reset when they save again. After 5 minutes, the session closes. Any save after that opens a new session.
We picked fixed-window over debounce on purpose. Debounce ("reset every save") makes the cadence unpredictable for both the customer and you.
State machine
A session is in one of three states:
| State | Meaning |
|---|---|
| Active | First save happened, less than 5 minutes ago, and not closed yet. |
| Completed | 5 minutes have passed since the first save. Locked in. |
| Cancelled | The customer cancelled the order during the session — supersedes everything. |
Only completed and cancelled sessions trigger merchant emails (in all events mode). Active sessions are visible on the Activity page live.
How sessions show up
On the Activity page
- Status column = session state.
- Last updated = timestamp of the last action in the session. Updates live while Active.
In the email
- One email per completed session in all events mode.
- Cancel breaks out: the cancel email fires the moment cancel happens, not when the session closes.
Counting against the cap
If you have Max edits per order on, the count is per session, not per save. 5 saves in 4 minutes = 1 session = +1 to the count.
What if the customer is on the page and the window closes mid-edit?
The save still goes through. We close the session at the 5-minute mark and the next save opens a new one. From the customer's perspective there is no UI change — they just keep editing. From your side, the activity log gets a second row.
Implementation notes (for the curious)
- We use a Cloud Tasks scheduled job that fires 5 minutes after the first save to close the session, snapshot the diff, and trigger the email.
- The session ID is stored on the
orderEditsdocument along withsessionStartAtandsessionStatus. - Concurrency: if two saves happen within milliseconds, we serialize on the order ID to avoid race conditions on the diff.