Duplicates and idempotency

# Duplicates and idempotency

Canonical: https://docs.flowrelay.app/recover/duplicates-and-idempotency/
Markdown: https://docs.flowrelay.app/recover/duplicates-and-idempotency.md

Duplicate protection and idempotency reduce accidental repeat work, but replay can intentionally bypass duplicate suppression when the operator confirms a second Shopify Flow handoff is desired.

## Sender event IDs
When possible, configure the sender to include a stable external event ID for each business event. FlowRelay can use that ID with the endpoint to identify repeated sends inside the dedupe window.


## Duplicate suppression versus replay
Duplicate suppression prevents an accidental repeated source send from causing a second automatic handoff. Manual replay is different: the operator is explicitly asking FlowRelay to hand the retained event to Shopify Flow again.


## Action idempotency
For governed actions, keep the idempotency key from preview through execute. If the target or action changes, start a new preview instead of reusing an old key.


## Operating guidance
Apply the concept through the receipt before changing setup, resending, or replaying.
1. Make sure the sender includes a stable external event ID when it can, so FlowRelay can identify repeated sends for the same endpoint.
2. Use the receipt outcome to distinguish duplicate suppression from a failed handoff or missing workflow.
3. Do not replay a duplicate-suppressed event unless a second Shopify Flow run is intentional.
4. For Agent Operations and governed actions, preserve the idempotency key from preview to execute.
5. If an idempotency key conflicts with a different target or action, stop and start a new explicit preview instead of reusing the old key.
6. Treat duplicate behavior as FlowRelay behavior, not as a configurable dedupe rule builder.

## Related
- [Event lifecycle](https://docs.flowrelay.app/operate/event-lifecycle.md)
- [Replay an event](https://docs.flowrelay.app/recover/replay.md)
- [Action intents](https://docs.flowrelay.app/reference/action-intents.md)

## Safety Boundary
Do not include raw payloads, endpoint secrets, auth headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.