Event lifecycle

# Event lifecycle

Canonical: https://docs.flowrelay.app/operate/event-lifecycle/
Markdown: https://docs.flowrelay.app/operate/event-lifecycle.md

Use lifecycle states to understand what FlowRelay has proved. Do not read them as a claim about downstream Shopify Flow actions.

## Lifecycle states
Use lifecycle states to understand the boundary FlowRelay has reached for a specific event.


- State: Accepted; What it proves: FlowRelay authenticated and durably stored the event before responding; Next safe action: Wait for processing to reach a terminal outcome before replaying or resending.
- State: Queued or processing; What it proves: FlowRelay is still working toward a terminal handoff result; Next safe action: Wait; do not replay or ask the sender to resend while processing is still active.
- State: Delivered; What it proves: FlowRelay handed the trigger to Shopify Flow; Next safe action: Inspect Shopify Flow separately if a branch or downstream action did not behave as expected.
- State: Failed; What it proves: FlowRelay reached a terminal validation, mapping, readiness, or handoff failure recorded by the receipt and support code; Next safe action: Follow the support code; use sender resend for rejected input or preview replay only when retained material and current setup make replay safe.
- State: Rejected; What it proves: FlowRelay did not accept a trusted replayable event because authentication, JSON, size, or another intake requirement failed; Next safe action: Correct the sender request and send a fresh event; there is no accepted event to replay.
- State: Waiting to retry; What it proves: FlowRelay is retrying the Shopify Flow handoff on its own schedule; Next safe action: Wait; no operator action is required yet.
- State: No workflow; What it proves: FlowRelay could not find a matching enabled Shopify Flow workflow; Next safe action: Enable the matching Shopify Flow trigger, then preview replay if the event is retained.
- State: Duplicate suppressed; What it proves: FlowRelay identified a repeated external event ID for the same endpoint inside the dedupe window; Next safe action: Open the linked first receipt and confirm whether the repeated send was expected.
- State: Manual review; What it proves: FlowRelay paused automatic recovery because Shopify Flow may already have received the handoff; Next safe action: Review diagnostics and the replay preview before approving any second handoff.
- State: Replayed; What it proves: A deliberate second attempt was made from retained event material; Next safe action: Inspect the linked replay attempt; the original receipt outcome is not rewritten.

## Manual review
Manual review means FlowRelay paused automatic recovery because Shopify Flow may already have received the handoff, so a duplicate Shopify Flow action could run. Use diagnostics and the replay preview before approving any second handoff.


## Retry and reconciliation
FlowRelay may reconcile accepted events that have not reached a terminal outcome. It does not expose merchant-configurable retry schedules or retry policy controls.


## Use the receipt for recovery
The receipt gives the support code, replay availability, diagnostics state, and safe next action for the event's current lifecycle state.


## Operating guidance
Apply the concept through the receipt before changing setup, resending, or replaying.
- Start with the receipt outcome: Accepted, Delivered, Failed, No workflow, Duplicate suppressed, or Rejected.
- Read the timeline to see whether FlowRelay stored the event, queued processing, evaluated duplicate suppression, attempted the Shopify Flow handoff, or recorded a terminal result.
- If the receipt says FlowRelay is waiting to retry, let FlowRelay make the next automatic handoff attempt instead of replaying or asking the sender to resend.
- Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.
- Treat No workflow as a setup/readiness problem: enable the matching Shopify Flow trigger, then preview replay while retained.
- Treat Duplicate suppressed as a sender retry or repeated external event ID that FlowRelay blocked from a second automatic handoff.
- Treat Manual review as a side-effect caution: review diagnostics and the replay preview before approving a second handoff.
- Use the recovery code and safe next action before replaying, resending, or changing endpoint configuration.

## Handoff Boundary
Delivered means FlowRelay handed the trigger to Shopify Flow. It does not mean downstream Shopify Flow branches, app calls, fulfillment changes, emails, or later systems completed.

## Related
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Event history](https://docs.flowrelay.app/operate/event-history.md)
- [Support codes](https://docs.flowrelay.app/recover/error-codes.md)

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.