Endpoint swap plan

# Endpoint swap plan

Canonical: https://docs.flowrelay.app/agent-access/endpoint-swap-plan/
Markdown: https://docs.flowrelay.app/agent-access/endpoint-swap-plan.md

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.

## Agent workflow
Agents should orient through docs before using authenticated tools.
1. Inventory current endpoints, senders, receivers, workflow purpose, current platform or source type, auth, owner, historical volume, criticality, and rollback path.
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 synthetic test 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.

## 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 recipes; reserve it for exceptional broader store operations.

- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes/): Choose 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.

```text
You are helping plan a safe FlowRelay endpoint swap for [store/domain].

Goal: inventory existing sender/receiver lanes, choose one low-risk pilot lane, prove one FlowRelay handoff, check plan fit, and prepare a broader cutover plan. Work only inside the store-scoped, time-bounded FlowRelay Agent Access grant for this task. Use Observer for read-only inventory, 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, raw event bodies, customer records, copied private logs, or store passwords.

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. Read the Agent Operations manifest at https://api.flowrelay.app/agent/v1/manifest.
3. Confirm the grant/store identity with whoami or GET /agent/v1/grant.
4. Read setup-state and plan-usage.

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
- 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 synthetic test event.
- 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, selected pilot and rationale, test result, plan fit, broader endpoint order, rollback path, stop conditions, monitoring cadence, unresolved approvals, and any future-edition request.
```


## Endpoint inventory
The agent should list the current sender, receiver or middleware, workflow purpose, event type, owner, auth method, historical event volume, criticality, last failure pattern, rollback owner, 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, synthetic test event, 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.


## 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.


## Related
- [Set up with an agent](https://docs.flowrelay.app/agent-access/setup-with-an-agent.md)
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits.md)
- [Read receipts](https://docs.flowrelay.app/operate/receipts.md)
- [Retries, replay, and resend](https://docs.flowrelay.app/recover/retries-replay-and-resend.md)
- [Support, expansion, and feature requests](https://docs.flowrelay.app/agent-access/support-and-expansion-requests.md)

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