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 uses that ID with the endpoint to identify repeated sends inside the current 30-day dedupe window. If the sender omits an external event ID, FlowRelay cannot apply this cross-request duplicate-suppression key; receipts and the sender's own idempotency remain the authoritative evidence.


## 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 approved 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.
- Make sure the sender includes a stable external event ID when it can, so FlowRelay can identify repeated sends for the same endpoint.
- Use the receipt outcome to distinguish duplicate suppression from a failed handoff or missing workflow.
- Do not replay a duplicate-suppressed event unless a second Shopify Flow run is intentional.
- For approved actions, preserve the idempotency key from preview to execute.
- If an idempotency key conflicts with a different target or action, stop and start a new explicit preview instead of reusing the old key.
- 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 previews](https://docs.flowrelay.app/reference/action-intents.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.