FlowRelay FlowRelay Docs Shopify Flow
Website → Set up FlowRelay →
All docs pages

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE

Agent Access

Endpoint swap plan

Use this guide when an operator already has a sender, receiver, webhook app, middleware, or serverless lane and wants to test one safe swap to FlowRelay first.

Reference Read Usage limits.

Agent workflow

Agents should orient through docs before using authenticated tools.

  1. Inventory candidate lanes from available evidence before assuming FlowRelay already has endpoints or receipts: senders, receivers, workflow purpose, current platform or source type, auth category, owner, historical volume, criticality, rollback path, evidence source, confidence, and access gaps.

  2. Classify the current path as supported now, Shopify Flow-only setup, or future-edition demand. Unsupported platform requests can become expansion requests only when tied to FlowRelay event reliability.

  3. Choose one pilot endpoint that is low-risk, least-used, rollback-friendly, and representative enough to prove the handoff.

  4. Check plan-usage and compare historical event volume, replay/diagnostics expectations, and agent-operation needs to the operator's current plan before recommending broader rollout.

  5. Stop for operator approval before changing the sender URL/auth or moving any production traffic.

  6. Run one test event with synthetic data on Free/Test or the current plan, then confirm FlowRelay accepted it and handed it to Shopify Flow.

  7. If the pilot works, produce a cutover plan for the remaining endpoints with sequence, owners, rollback, stop conditions, monitoring cadence, and capacity needs.

Operating rules

  • Stop for operator approval before changing the sender URL/auth or moving any production traffic.

  • Revoke the grant when the work is finished or when the partner no longer needs access.

  • Review audit entries for sensitive reads, action previews, confirmations, replays, and diagnostics shares.

Grant needed #

Use a store-scoped, time-bounded Agent Access grant for the exact swap-planning job. Observer is enough for inventory and read-only review. Operator is the default when the agent may create or edit endpoint setup or prepare endpoint tests for the pilot. Recovery Operator is required only when the pilot includes replay, diagnostics share creation, or secret rotation. Do not use Admin Assistant for normal swap-planning guides; reserve it for exceptional broader store operations.

  • Grants and scopesChoose the lowest useful authority tier before starting the swap plan.

Copyable agent instructions #

Paste this into an authorized agent session before any sender, receiver, or workflow is changed. Replace bracketed details, keep tokens in environment variables or the agent client's secret store, and keep private payloads or secrets out of the brief.

Agent swap-planning brief Use for one existing sender lane before a broader migration. 
You are helping plan a safe FlowRelay endpoint swap for [store/domain].

Goal: inventory candidate sender/receiver lanes from available evidence, choose one low-risk pilot lane, prove one FlowRelay handoff when authorized, check plan fit if FlowRelay is already installed, and prepare a broader cutover plan. Do not assume FlowRelay already has endpoints, receipts, setup state, or plan data. Work only inside the store-scoped, time-bounded FlowRelay Agent Access grant for this task when a grant exists. Use Observer for read-only FlowRelay review, Operator when endpoint setup changes or endpoint tests are authorized, and Recovery Operator only if replay, diagnostics share creation, or secret rotation is explicitly in scope. Do not ask for endpoint secrets, authentication headers, HMAC values, Shopify tokens, session data, raw event bodies, customer records, database URLs, store passwords, copied private logs, or screenshots containing private values.

Token handling:
- Receive the scoped Agent Access token only through private secret, environment variable, CLI profile, or MCP host secret configuration.
- Never paste the token into prompts, docs, tickets, screenshots, logs, repo files, or shared notes.

Before changing anything:
1. Read https://docs.flowrelay.app/llms.txt and https://docs.flowrelay.app/agent-access/endpoint-swap-plan/.
2. If FlowRelay is already installed and an Agent Access grant exists, read the Agent Operations manifest at https://api.flowrelay.app/agent/v1/manifest and confirm the grant/store identity with whoami or GET /agent/v1/grant.
3. If FlowRelay is already installed, read setup-state and plan-usage before broad reads, polling, or recommending rollout capacity.
4. If FlowRelay is not installed or no grant exists, mark FlowRelay data as unavailable and inventory from safe merchant/admin evidence only.

Inventory each candidate lane:
- sender/source system, receiver/middleware, owner, current platform/source type
- workflow purpose and Shopify Flow trigger variant fit
- authentication method and retry behavior
- historical event volume, criticality, recent failures, and rollback path
- evidence source, confidence level, access gap, and next evidence step
- whether the lane maps to FlowRelay for Shopify Flow today or should become a future-edition request

Pilot choice:
- Pick one safest, least-used, rollback-friendly lane with a clear owner and a test event with synthetic data.
- Stop for operator approval before changing sender URL/auth, Shopify Flow workflows, billing/capacity, grants, replay, diagnostics sharing, or production traffic.
- Prove FlowRelay accepted and handed off one event; downstream Shopify Flow branch/action success must be confirmed separately by the operator.
- If FlowRelay returns 429, obey Retry-After, retryAfterSeconds, resetAt, rateLimitClass, scope, and recommendedAction.

Final output:
Give the operator an inventory table with evidence/confidence/gaps, selected pilot and rationale, test result if a FlowRelay handoff was authorized, plan fit if available, broader endpoint order, rollback path, stop conditions, monitoring cadence, unresolved approvals, and any future-edition request.

Endpoint inventory #

Build the inventory from evidence, not assumption. Do not assume which lanes are FlowRelay endpoints or what receipts exist - read them first. Then classify each lane: supported now, Shopify Flow setup only, or future-edition demand (review record only, not a live target).

Include the current sender, receiver or middleware, workflow purpose, event type if known, owner, auth category, historical event volume, criticality, last failure pattern, rollback owner, evidence source, confidence, access gaps, and whether the lane maps to the current Shopify Flow edition. This inventory should not include secrets, auth header values, raw payloads, customer records, or private logs.

Pilot selection #

Pick one endpoint for testing before a broader migration. Prefer the safest, least-used, reversible lane with a clear owner, a test event with synthetic data, known Shopify Flow trigger, and observable downstream test result. Do not bulk-swap first.

Plan fit #

Compare historical accepted-event volume plus expected migration traffic against the current plan and paid-plan grace. Also check diagnostics, replay, simple reads, rich reads, action previews, and executed actions for the work the agent plans to do. If volume may exceed the plan, recommend upgrade, custom capacity, or a smaller cutover window before production traffic moves.

Cutover and rollback #

The cutover plan should name each endpoint lane, owner, scheduled order, sender-side change, FlowRelay endpoint, expected receipt proof, rollback trigger, old receiver restoration path, stop condition, and who approves continuing to the next lane. 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. Confirm downstream completion separately before widening cutover.

Monitoring cadence #

Recommend cadence from historical usage and importance: close checks during the pilot and immediately after cutover, lighter periodic checks for low-volume lanes, and more frequent checks for critical or high-volume lanes. Agents should use compact reads first, plan-usage before broad polling, and Retry-After/resetAt guidance when a 429 rate-limit response appears.

Operator summary #

End with a simple operator-readable plan: inventory table, selected pilot and why, test result, plan fit, broader endpoint order, rollback and stop conditions, monitoring cadence, unresolved approvals, and any future-edition expansion request.