FlowRelay Docs for Shopify Flow

# FlowRelay Docs for Shopify Flow

Canonical: https://docs.flowrelay.app/
Markdown: https://docs.flowrelay.app/index.md

Choose the job in front of you: set up FlowRelay, investigate an event, move an existing event path, or use Agent Access and machine references.

## What do you need to do?

### Set up FlowRelay
Create an endpoint, connect Shopify Flow, and prove one safe test event before production traffic.

- Start with your first endpoint: https://docs.flowrelay.app/getting-started/first-endpoint/
- How FlowRelay works: https://docs.flowrelay.app/getting-started/

### Investigate or recover an event
Read the receipt, identify where the handoff stopped, and choose a safe next action.

- Recover a failed handoff: https://docs.flowrelay.app/use-cases/recover-failed-handoff/
- Look up a support code: https://docs.flowrelay.app/recover/error-codes/

### Move an existing event path
Replace a webhook, custom receiver, or manual path with a pilot, receipt proof, and rollback plan.

- Plan a safe swapover: https://docs.flowrelay.app/use-cases/swapover-to-flowrelay/
- Open the partner kit: https://docs.flowrelay.app/use-cases/agency-developer-partner-kit/

### Use Agent Access and machine references
Give an authorized agent scoped access, or open the API, CLI, MCP, and OpenAPI references.

- Start with Agent Access: https://docs.flowrelay.app/agent-access/
- Open the API reference: https://docs.flowrelay.app/reference/api/

## Browse all documentation

### Start
- [How it works](https://docs.flowrelay.app/getting-started/): Overview of FlowRelay setup, receipts, recovery, Agent Access, and references for Shopify Flow.
- [First endpoint guide](https://docs.flowrelay.app/getting-started/first-endpoint/): Concise first endpoint setup path for a Shopify Flow user new to FlowRelay.
- [Send your first test event](https://docs.flowrelay.app/getting-started/first-event/): Shortest safe path from FlowRelay endpoint setup to one Delivered receipt in Shopify Flow.

### Use Cases
- [External events into Shopify Flow](https://docs.flowrelay.app/use-cases/external-events-to-shopify-flow/): Use FlowRelay when an outside system needs to start a Shopify Flow workflow reliably.
- [Swap over to FlowRelay](https://docs.flowrelay.app/use-cases/swapover-to-flowrelay/): Plan a safe move from an existing webhook, custom receiver, middleware path, or manual handoff to FlowRelay.
- [Agency & developer partner kit](https://docs.flowrelay.app/use-cases/agency-developer-partner-kit/): Partner coordination guide for setting up or moving one client's external event path into Shopify Flow.
- [Recover a failed handoff](https://docs.flowrelay.app/use-cases/recover-failed-handoff/): Use receipts, support codes, replay, and diagnostics when an event did not reach a clean Shopify Flow handoff.
- [Work with a partner without sharing secrets](https://docs.flowrelay.app/use-cases/share-diagnostics-with-partner/): Give a sender owner, setup partner, or FlowRelay support enough evidence to help without exposing event bodies, authentication headers, or secrets.
- [Let an agent investigate an event](https://docs.flowrelay.app/use-cases/agent-assisted-operations/): Use Agent Access when a merchant wants an authorized agent to inspect a FlowRelay receipt and prepare safe recovery.

### Set Up
- [Create an endpoint](https://docs.flowrelay.app/setup/endpoints/): Create and manage the private sender-facing FlowRelay endpoint for Shopify Flow.
- [Authenticate requests](https://docs.flowrelay.app/setup/authentication/): Choose HMAC-SHA256 or static-header authentication while keeping secret material private.
- [Event types and payloads](https://docs.flowrelay.app/setup/event-types-and-payloads/): Choose the FlowRelay trigger variant and payload requirements that match the Shopify Flow workflow.
- [Permissions and data access](https://docs.flowrelay.app/setup/permissions-and-data-access/): When FlowRelay requests optional Shopify read scopes for native Shopify Flow references and what data FlowRelay does not query or sync.
- [Trigger variants and mapping](https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/): Field-by-field reference for Shopify Flow trigger variants, resource identifiers, and endpoint event mapping.
- [Rotate credentials](https://docs.flowrelay.app/setup/rotate-credentials/): Replace a FlowRelay endpoint secret when access changes or secret material may be exposed.
- [Add the Shopify Flow trigger](https://docs.flowrelay.app/setup/shopify-flow-trigger/): Enable the matching FlowRelay trigger inside Shopify Flow.

### Operate
- [Read receipts](https://docs.flowrelay.app/operate/receipts/): Read FlowRelay receipt facts, handoff status, recovery context, and redacted support summaries.
- [Event history](https://docs.flowrelay.app/operate/event-history/): Find accepted, delivered, failed, replayed, and retained events without exposing private event bodies.
- [Event lifecycle](https://docs.flowrelay.app/operate/event-lifecycle/): FlowRelay event states from durable acceptance through Shopify Flow handoff, duplicate suppression, replay, or recovery.
- [Retention](https://docs.flowrelay.app/operate/retention/): What FlowRelay keeps, what expires, and how retention affects replay and diagnostics.
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits/): Plan capacity, what counts against usage, paid-plan grace, and operational safeguards.

### Recover
- [Support codes](https://docs.flowrelay.app/recover/error-codes/): Stable FlowRelay support-code explanations and recovery actions.
- [Retries, replay, and resend](https://docs.flowrelay.app/recover/retries-replay-and-resend/): Separate sender retries, FlowRelay processing reconciliation, and deliberate replay.
- [Replay an event](https://docs.flowrelay.app/recover/replay/): Replay guidance for availability, side-effect caution, preview, confirmation, and audit.
- [Duplicates and idempotency](https://docs.flowrelay.app/recover/duplicates-and-idempotency/): How FlowRelay suppresses duplicate external event IDs and uses idempotency for approved actions.
- [Share diagnostics](https://docs.flowrelay.app/recover/diagnostics/): Preview-first, redacted diagnostics sharing for FlowRelay support and partner collaboration.
- [Work with support](https://docs.flowrelay.app/recover/support-signals/): Use FlowRelay receipts and diagnostics when support needs evidence about an event, endpoint, or recovery action.

### Agent Access
- [Overview](https://docs.flowrelay.app/agent-access/): What FlowRelay Agent Access is, what an authorized agent can do, and what stays under human control — scoped grants, redaction, approval, and audit.
- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes/): Authority tiers, scope boundaries, expiry, revocation, and audit for Agent Access.
- [Agent orientation](https://docs.flowrelay.app/agent-access/agent-orientation/): Orientation page for authorized agents using FlowRelay docs, Markdown pages, llms.txt, OpenAPI, CLI, MCP, and the FlowRelay Operator Skill.
- [Rate limits](https://docs.flowrelay.app/agent-access/rate-limits-and-backoff/): FlowRelay rate-limit policy, 429 response handling, and default safeguards for agents, API clients, CLI, MCP, and sender integrations.
- [Choose an agent mission](https://docs.flowrelay.app/agent-access/agent-mission-playbooks/): Choose the FlowRelay mission that matches an operator's task, then gather context and act within the current grant.
- [Shopify Sidekick](https://docs.flowrelay.app/agent-access/shopify-sidekick/): FlowRelay's Shopify Sidekick integration is temporarily unavailable while it is aligned with Shopify's current extension requirements.
- [New setup with an agent](https://docs.flowrelay.app/agent-access/setup-with-an-agent/): Create one new FlowRelay endpoint with an authorized agent, prove one Shopify Flow handoff, and return control to the operator.
- [Existing-path swap with an agent](https://docs.flowrelay.app/agent-access/endpoint-swap-plan/): Use an authorized agent to inventory, pilot, and plan the cutover of one existing sender or receiver path to FlowRelay.
- [Availability and refusals](https://docs.flowrelay.app/agent-access/availability-and-refusals/): How FlowRelay decides whether an agent action is available, blocked, human-only, or outside the current Shopify Flow edition.
- [FlowRelay Operator Skill](https://docs.flowrelay.app/agent-access/skills/): Installable FlowRelay skill for controlled Shopify Flow event operations, setup, receipt investigation, recovery, and support.
- [Support, expansion, and feature requests](https://docs.flowrelay.app/agent-access/support-and-expansion-requests/): Choose and prepare a structured Agent Access request for active support, future-edition demand, or a missing FlowRelay capability.

### Reference
- [Glossary](https://docs.flowrelay.app/reference/glossary/): Plain-language meanings for the FlowRelay terms you see in setup, receipts, recovery, Agent Access, and usage docs.
- [API Reference](https://docs.flowrelay.app/reference/api/): The Agent Operations API is the canonical machine-access contract for FlowRelay. The API, CLI, and MCP are access surfaces over this one contract; they do not grant separate authority. Use the generated effect model to distinguish reads, handoffs, previewed actions, and direct resource creation.
- [CLI Reference](https://docs.flowrelay.app/reference/cli/): JSON-first CLI wrapper over Agent Operations, including docs discovery and doctor commands.
- [MCP Reference](https://docs.flowrelay.app/reference/mcp/): MCP Agent Operations access over the same scoped Agent Operations contract when enabled.
- [Action previews](https://docs.flowrelay.app/reference/action-intents/): Preview, confirmation, idempotency, metering, audit, and refusal behavior for approved actions.
- [OpenAPI](https://docs.flowrelay.app/reference/openapi/): Generated OpenAPI schema discovery and public contract placement for Agent Operations.

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