FlowRelay
Agent Access
Availability and refusals
A capability being listed in the manifest does not mean an agent may execute it. Availability depends on authority, plan usage, target state, safety rules, and product boundaries.
On this page
Operating rules
Read the manifest to learn which capabilities exist in the current Shopify Flow edition.
Read the grant to learn which scopes the merchant authorized for this agent.
Read plan usage before broad reads, loops, repeated previews, or recovery work.
Read the target endpoint, event, diagnostics share, or setup state before deciding whether the object is actionable.
Use action previews and idempotency for work that changes setup or recovery state.
Return the refusal reason and next safe action when any availability layer blocks the request.
Availability model #
A capability appearing in the manifest means it exists, not that this agent may run it here. A route can exist and still be unavailable, because authority, plan state, target object, and safety boundaries are all checked at execution.
| Layer | Question | Where to check | If blocked |
|---|---|---|---|
| Capability | Does FlowRelay expose this operation in the current edition? | /agent/v1/manifest capabilityDetails and OpenAPI. | Explain that the operation is unavailable in the current Shopify Flow edition. |
| Authority | Did the merchant grant this agent the required scopes? | /agent/v1/grant and requiredScopes in manifest or OpenAPI. | Ask an authorized human to change the grant or perform the action. |
| Usage | Is there remaining plan capacity for the read, preview, or execution? | /agent/v1/plan-usage and the Usage limits page. | Reduce work, wait for reset, or ask a human to approve more capacity. |
| Target state | Is the endpoint, event, receipt, retained material, or diagnostics share in a state that supports the action? | Setup state, endpoint detail, event detail, receipt facts, retention state, and diagnostics state. | Use the safe next action, such as sender resend, setup fix, or diagnostics. |
| Safety | Does the action require preview, confirmation, idempotency, redaction, or human judgment? | Action preview docs, operation metadata, and refusal response. | Preview first, request confirmation, redact, or escalate. |
| Product boundary | Is the request within FlowRelay for Shopify Flow? | Manifest platform identity, docs, and support or expansion guidance. | Explain the boundary or submit an expansion request only when it is tied to FlowRelay's event reliability mission. |
Common refusals #
Refusals should be treated as product guidance, not generic errors. The agent should report the reason, the evidence, and the next safe action.
| Refusal type | Meaning | Next safe action |
|---|---|---|
| Missing scope | The merchant did not authorize this agent for the operation. | Ask an authorized human to perform the action or issue a more appropriate grant. |
| Human-only | The action stays under human control even if the agent can read related context. | Prepare a handoff with links and context, but do not execute. |
| Usage limit | The plan meter or temporary safeguard does not allow more of this work right now. | Stop loops, reduce reads or previews, wait for reset, or ask a human to approve more capacity. |
| Retention expired | FlowRelay no longer has replayable event material. | Ask the sender to send a fresh event rather than reconstructing private data. |
| Unsafe replay | Replay could duplicate downstream Shopify Flow actions or the required confirmation is missing. | Use replay preview, inspect downstream risk, and get explicit confirmation from an authorized operator. |
| Unsupported platform or capability | The request is outside the current Shopify Flow edition. | Explain the boundary, submit an in-bounds expansion request for future-edition demand, or submit a feature request only when the missing capability belongs inside FlowRelay. |
| Generic wishlist | The request does not identify a FlowRelay reliability, receipt, recovery, diagnostics, Agent Operations, billing/usage, security, or docs gap. | Ask the operator to restate the concrete FlowRelay workflow, or decline instead of filing product-demand noise. |
| Ambiguous mapping | The correct trigger variant or identifier path is not clear from the operator's request or sender payload. | Use the trigger mapping reference and ask the operator to confirm before creating or editing the endpoint. |
How to respond #
First distinguish a temporary safeguard from a hard refusal. A temporary 429 names retry timing and permits a bounded retry after Retry-After or resetAt; missing scope, human-only approval, unsafe action, expired retention, and product-boundary refusals do not. For a hard refusal, name the blocking layer, cite the relevant FlowRelay fact or docs URL, avoid asking for private data, and offer the next safe action. Do not retry around it or seek another surface to bypass it. The response should not imply that a broader Shopify, billing, or platform action is available through FlowRelay.
API CLI MCP parity #
Direct API calls, the FlowRelay CLI, and MCP Agent Operations access all use the same manifest, scopes, OpenAPI contract, usage limits, action previews, redaction rules, audit model, and refusal semantics. A different surface does not create different authority.