A model can request a refund. Your application must decide whether it is allowed.
Build the agent around a versioned GraphQL adapter, a verified event inbox and a durable action ledger. The language model proposes work; deterministic code checks identity, policy, money and permissions. Use query-cost telemetry to schedule reads and treat webhook delivery as a notification to reconcile, not as an exactly-once instruction to mutate an order.
What changed—and what the sources establish
Shopify’s GraphQL Admin API uses calculated query cost. Read requested and actual cost and throttle status rather than copying a generic requests-per-second limit from REST tutorials. Limits differ by plan and can change under platform pressure. Shopify GraphQL Admin API rate limits.
The official schedule identifies 2026-10 as the latest stable API on 11 October 2026. Pin a supported version, test upgrades quarterly and inspect the response version header; requests to inaccessible versions can fall forward. Shopify API versioning.
Shopify requires HTTPS webhook verification against the raw request body and documents duplicate detection and a five-second response window. Persist verified events promptly, acknowledge them, then perform slower work outside the delivery request. Shopify webhook delivery verification.
The 2026-10 refundCreate reference returns mutation errors and shows an @idempotent directive in examples. Check the selected mutation’s documented support instead of assuming every write accepts the same idempotency mechanism. Shopify 2026-10 refundCreate.
Choose the approach that fits the constraint
Separate control planes with different failure behavior. An app can need all four patterns without making the LLM responsible for any of their correctness.
| Situation | Start here | Tradeoff / acceptance check |
|---|---|---|
| Interactive customer question | Small scoped GraphQL read | Return current facts; reserve cost capacity |
| Large backfill or reporting job | Bulk or queued extraction | Do not starve customer-facing calls |
| Order-change notification | Verified durable webhook inbox | Deduplicate and reconcile live state |
| Refund or fulfillment write | Authorized command plus ledger | Validate money, use supported idempotency, read back |
Budget GraphQL cost per store, not per conversation
An agent conversation can trigger several reads even when the customer asks one question. Cache stable catalog data within a defined freshness window, request only necessary fields and cap pagination. Put background synchronization in a lower-priority queue. If customer support, finance reconciliation and product ingestion share the same app-store capacity, coordinate their scheduler instead of letting each worker independently retry until something succeeds.
Record the query fingerprint, requested cost, actual cost, available capacity and restore rate. Those observations explain throttling more usefully than a single error counter. A retry should wait for sufficient capacity and add jitter when many jobs are queued. Do not promise the customer a completed action while the adapter is still waiting. Expose pending state with a reference the user or operator can check.
Treat webhook events as durable hints about business state
Verify the HMAC before trusting the payload. Use the exact raw bytes before middleware changes the body, and reject invalid deliveries. Store the relevant shop identity, delivery/event identifiers, topic, API version and receipt time in an inbox with a uniqueness policy. The handler should persist the event and acknowledge it quickly. Model inference, policy evaluation and API writes belong in asynchronous workers.
Events can arrive again or out of order, and outages can leave gaps. Re-read the current order before taking a consequential action. Maintain a reconciliation job over changed records so a missed event does not become a permanently missed refund, cancellation or fulfillment update. Make the reconciliation window explicit and retain its checkpoint. A queue gives durability only if workers can safely resume after a crash.
Make the write path stricter than the reasoning path
Define narrow tools such as prepare_return or propose_refund instead of arbitrary GraphQL execution. The server derives shop and customer identity from authenticated context, verifies order ownership and calculates quantities and currency from live records. The model may explain why an item appears eligible, but an approved rule must determine eligibility, refund limits and whether human approval is required.
Assign a business command ID before the write. Where the mutation supports documented API idempotency, use it consistently across retries; keep the application ledger as well. Inspect userErrors and transaction state, then read back the resulting object. A transport timeout is an unknown outcome, not proof of failure. Reconcile that command before repeating it. Keep credentials and complete payment data out of model prompts.
Worked example: illustrative assumptions, not a reported result
Illustrative scheduling example: assume observed capacity restores at 100 cost points per second and each planned read requests 40 points. Twenty reads request 800 points. A burst may fit some currently available capacity, but sustained scheduling must respect the restore rate and other workloads. The simple steady-state ceiling is 100 ÷ 40 = 2.5 such reads per second before reserving capacity.
This is arithmetic using assumed telemetry, not a universal Shopify limit or a measured throughput claim. A refund requires a separate command budget and authorization path. If a worker times out after submitting command R-123, the recovery step looks up R-123 and the live order’s transaction state. It does not ask the model to invent a new refund because the previous response was missing.
Failure modes to catch before scaling
- Retry amplification: every worker retries immediately after throttling. Centralize scheduling and backoff per app-store capacity.
- Replay writes: duplicate events or timeouts trigger repeat refunds. Persist commands, use supported idempotency and reconcile uncertain outcomes.
- Silent version drift: retired requests fall forward. Alert on response-version mismatch and validate mutation inputs and webhook contracts before migration.
Rate-limit handling does not establish business correctness. A successful API response can still represent the wrong order, quantity or permission. Test adverse cases at the adapter and policy boundaries.
A concrete next step
Pick one read-only support workflow. Pin API 2026-10, record cost telemetry, implement a verified webhook inbox and demonstrate recovery from duplicate delivery, throttling and worker restart before enabling any financial write.
| Owner | Integration engineer owns adapter; commerce owner approves policy |
|---|---|
| Evidence | Version headers, cost telemetry, event inbox and command ledger |
| Recovery | Reconciliation checkpoint and unknown-outcome procedure |
| Acceptance | No duplicate business action under replay; correct read-back state |
Test on development-store fixtures for partial refunds, multi-currency orders, canceled orders and insufficient permissions. Keep actual GraphQL operations in a versioned codebase and validate them against the chosen schema. Document which mutations support platform idempotency and which depend on application-level deduplication.
Practical questions
Which Shopify API version should a new agent use?
As of 11 October 2026, 2026-10 is the latest stable version. Pin a supported stable version, test it and monitor the actual response version rather than using unstable or silently depending on latest.
Can I use a fixed requests-per-second limit for GraphQL?
GraphQL Admin uses calculated query cost. Schedule using the response cost and throttle telemetry for the app-store context, including background workloads and the store’s applicable plan.
Should the webhook handler call the model before responding?
No. Verify and durably persist the event, acknowledge within the documented delivery window, then run slower processing asynchronously. Add reconciliation for missed and out-of-order events.
Does an HTTP success mean the refund completed?
No. Inspect mutation userErrors, the returned refund and transaction states, then reconcile live records. Treat transport timeouts as uncertain outcomes and avoid blindly repeating the write.
Primary sources checked 11 October 2026
- Shopify GraphQL Admin API rate limits — GraphQL Admin rate limits use calculated query cost and expose throttle status for adaptive scheduling.
- Shopify API versioning — 2026-10 is latest stable on October 11, 2026; versions are released quarterly and inaccessible versions fall forward.
- Shopify webhook delivery verification — Verify the HMAC using raw body, detect duplicates, acknowledge within five seconds and process asynchronously.
- Shopify 2026-10 refundCreate — refundCreate supports full or partial refunds, returns userErrors and documents an @idempotent directive in examples.
The calculations in this guide are illustrative planning examples. Product documentation establishes supported features and conditions; it does not establish a measured return for your organization. Recheck account availability and release notes when implementing the recommendation.
Continue with Return resolution architecture and Agent action guardrails.
Research Path