Availability and refusals

# Availability and refusals

Canonical: https://docs.flowrelay.app/agent-access/availability-and-refusals/
Markdown: https://docs.flowrelay.app/agent-access/availability-and-refusals.md

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.

## Availability model
An agent action is available only when every required layer allows it. A route can exist and still be unavailable for the current grant, plan state, target object, or safety boundary.


- Layer: Capability; Question: Does FlowRelay expose this operation in the current edition?; Where to check: /agent/v1/manifest capabilityDetails and OpenAPI.; If blocked: Explain that the operation is unavailable in the current Shopify Flow edition.
- Layer: Authority; Question: Did the merchant grant this agent the required scopes?; Where to check: /agent/v1/grant and requiredScopes in manifest or OpenAPI.; If blocked: Ask an authorized human to change the grant or perform the action.
- Layer: Usage; Question: Is there remaining plan capacity for the read, preview, or execution?; Where to check: /agent/v1/plan-usage and the Usage limits page.; If blocked: Reduce work, wait for reset, or ask a human to approve more capacity.
- Layer: Target state; Question: Is the endpoint, event, receipt, retained material, or diagnostics share in a state that supports the action?; Where to check: Setup state, endpoint detail, event detail, receipt facts, retention state, and diagnostics state.; If blocked: Use the safe next action, such as sender resend, setup fix, or diagnostics.
- Layer: Safety; Question: Does the action require preview, confirmation, idempotency, redaction, or human judgment?; Where to check: Action preview docs, operation metadata, and refusal response.; If blocked: Preview first, request confirmation, redact, or escalate.
- Layer: Product boundary; Question: Is the request within FlowRelay for Shopify Flow?; Where to check: Manifest platform identity, docs, and support or expansion guidance.; If blocked: 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: Missing scope; Meaning: The merchant did not authorize this agent for the operation.; Next safe action: Ask an authorized human to perform the action or issue a more appropriate grant.
- Refusal type: Human-only; Meaning: The action stays under human control even if the agent can read related context.; Next safe action: Prepare a handoff with links and context, but do not execute.
- Refusal type: Usage limit; Meaning: The plan's published meter does not allow more of this work in the current period.; Next safe action: Stop loops, reduce reads or previews, wait for reset, or ask a human to approve more capacity.
- Refusal type: Retention expired; Meaning: FlowRelay no longer has replayable event material.; Next safe action: Ask the sender to send a fresh event rather than reconstructing private data.
- Refusal type: Unsafe replay; Meaning: Replay could duplicate downstream Shopify Flow actions or the required confirmation is missing.; Next safe action: Use replay preview, inspect downstream risk, and get explicit confirmation from an authorized operator.
- Refusal type: Unsupported platform or capability; Meaning: The request is outside the current Shopify Flow edition.; Next safe action: Explain the boundary or submit an in-bounds expansion request when the merchant asked for FlowRelay-adjacent support.
- Refusal type: Ambiguous mapping; Meaning: The correct trigger variant or identifier path is not clear from the operator's request or sender payload.; Next safe action: Use the trigger mapping reference and ask the operator to confirm before creating or editing the endpoint.

## How to respond
When an action is unavailable, the agent should name the blocking layer, cite the relevant FlowRelay fact or docs URL, avoid asking for private data, and offer the next safe action. 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.


## Operating rules
Use these controls to keep agent access scoped and reversible.
1. Read the manifest to learn which capabilities exist in the current Shopify Flow edition.
2. Read the grant to learn which scopes the merchant authorized for this agent.
3. Read plan usage before broad reads, loops, repeated previews, or recovery work.
4. Read the target endpoint, event, diagnostics share, or setup state before deciding whether the object is actionable.
5. Use action previews and idempotency for side-effecting work.
6. Return the refusal reason and next safe action when any availability layer blocks the request.

## Related
- [Agent mission playbooks](https://docs.flowrelay.app/agent-access/agent-mission-playbooks.md)
- [Grants and scopes](https://docs.flowrelay.app/agent-access/grants-and-scopes.md)
- [Usage limits](https://docs.flowrelay.app/operate/usage-limits.md)
- [Action previews](https://docs.flowrelay.app/reference/action-intents.md)
- [API Reference](https://docs.flowrelay.app/reference/api.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.