Swap over to FlowRelay

# Swap over to FlowRelay

Canonical: https://docs.flowrelay.app/use-cases/swapover-to-flowrelay/
Markdown: https://docs.flowrelay.app/use-cases/swapover-to-flowrelay.md

Use this guide when a merchant or technical owner is planning the move from an existing event path to FlowRelay. It covers the pilot, receipt proof, rollback, and phased cutover; if an authorized agent will inventory or carry out the move, use Move an existing event path with an agent.

## Why swap over
FlowRelay is useful when the brittle part is not just receiving a webhook. The hard part is knowing what arrived, what auth passed, what mapping was active, whether Shopify Flow was ready, whether a replay is safe, and what evidence support or an authorized agent can use without digging through scattered logs.


## Start before FlowRelay exists
A pre-adoption merchant may not have any FlowRelay endpoints, receipts, or plan data yet. Start with a candidate-path inventory built from Shopify Admin context, current webhook or automation apps, provider exports, middleware runbooks, serverless functions, logs the operator can safely summarize, and merchant knowledge. Label every row with its evidence source, confidence, access gap, and next evidence step. Do not ask for endpoint secrets, raw payloads, auth header values, customer data, tokens, copied private logs, or store passwords.


- Field: Sender/source; Good evidence: Provider, app, middleware, serverless function, ERP, WMS, CRM, or manual process name; If missing: Ask the operator which system currently initiates the work.
- Field: Receiver/current path; Good evidence: Webhook app, middleware URL owner, script, queue, Zapier/Make lane, or Shopify Flow trigger clue; If missing: Mark as access gap; do not guess from unrelated FlowRelay data.
- Field: Shopify Flow tie; Good evidence: Workflow name, trigger name, condition text, log marker, or operator-confirmed downstream action; If missing: Treat as suspected only and require Shopify Admin review before cutover.
- Field: Pilot safety; Good evidence: Low volume, reversible action, harmless test branch, clear rollback owner, and a test path with synthetic data; If missing: Do not choose this path as the first pilot.

## Safe migration sequence
Use one pilot before the broader cutover. The sequence is: create endpoint, wire a test sender, enable the Shopify Flow workflow, send a test event, verify the receipt, then cut over the production sender. Do not change the sender URL/auth or production traffic before the receipt proof and rollback owner are clear.


- Step: Create endpoint; Proof to collect: Endpoint name, trigger variant, auth mode, required mapping paths, and plan fit; Stop if: The trigger variant or required Shopify reference is unclear.
- Step: Wire test sender; Proof to collect: Synthetic payload, private auth configuration, and expected external event ID behavior; Stop if: The sender owner cannot test without exposing secrets or customer data.
- Step: Enable Flow workflow; Proof to collect: Matching FlowRelay trigger is enabled and the test action is safe; Stop if: The workflow might perform customer-visible or irreversible actions during the pilot.
- Step: Verify receipt; Proof to collect: A Delivered receipt, support code if any, replay state, diagnostics-share availability, and a separate downstream Shopify Flow result check when outcome matters; Stop if: The result is no_workflow, mapping failed, auth failed, or downstream behavior is unconfirmed.
- Step: Cut over; Proof to collect: Cutover window, rollback path, sender owner, monitoring cadence, and stop conditions; Stop if: Rollback cannot be performed quickly or plan capacity is not sufficient.

## What FlowRelay adds during migration
Receipts make each event discussable. Replay previews show whether retained material can be handed to Shopify Flow again and what side effects may repeat. Diagnostics shares let a partner or support team inspect redacted setup and receipt facts. Idempotency helps suppress accidental duplicate sender retries and keeps approved actions tied to the preview that created them. Endpoint secrets keep sender access private, and Flow handoff status separates FlowRelay proof from downstream Shopify Flow behavior.


## Why this is easier to trust
The change is not that events move faster. It is that every event now leaves an evidence trail — a receipt, a support code, a replay state, a diagnostics share — so a failure becomes a question you can answer instead of one you have to reconstruct. Human and authorized agent operators work from those stable facts instead of reconstructing them.


## Keep the old path until the new one is proven
The current webhook app, custom code, or manual process got the store this far — treat it as infrastructure to replace carefully, not a mistake to delete. Keep it available as the rollback path until the FlowRelay receipt proves the pilot works end to end, and only then retire old paths one at a time.


## Cutover checklist
Before production cutover, confirm: the pilot endpoint shows Delivered (FlowRelay handed the trigger to Shopify Flow), downstream Shopify Flow behavior was checked separately, production sender auth is ready, rollback owner is available, plan capacity fits expected traffic, diagnostics sharing is available, and support knows not to ask for raw payloads, endpoint secrets, auth headers, tokens, or session data.


## Typical path
A typical path starts from the scenario, then moves into setup and verification.
1. Inventory the current paths
   Inventory candidate event paths from available evidence first: sender/source, current receiver or app, auth category, owner, event volume, criticality, retry behavior, rollback path, suspected Shopify Flow workflow, evidence source, confidence, and access gaps.
2. Choose one pilot
   Choose one low-risk pilot path before moving production traffic broadly.
3. Create the pilot endpoint
   Create the FlowRelay endpoint and choose the matching trigger variant and authentication method.
4. Connect a test sender
   Wire a test sender or sandbox sender to the FlowRelay endpoint without changing the production sender yet.
5. Enable a safe workflow
   Enable the matching Shopify Flow workflow with a harmless test action or controlled pilot branch.
6. Prove the handoff
   Send one test event with synthetic data and verify the FlowRelay receipt, support code, replay availability, and diagnostics-share path.
7. Move traffic gradually
   Only after proof, cut over the production sender URL/auth for the pilot path during an agreed window.
8. Monitor and roll back if needed
   Monitor event history, receipts, usage, and downstream Shopify Flow behavior, then expand one path at a time.

## 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
- [First endpoint guide](https://docs.flowrelay.app/getting-started/first-endpoint.md)
- [Agency & developer partner kit](https://docs.flowrelay.app/use-cases/agency-developer-partner-kit.md)
- [Existing-path swap with an agent](https://docs.flowrelay.app/agent-access/endpoint-swap-plan.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Retries, replay, and resend](https://docs.flowrelay.app/recover/retries-replay-and-resend.md)
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics.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.