Understanding Subrequest Budgets in Shopify (2025)

By nuwudorder | September 22, 2025

Shopify’s Oxygen hosting enforces something many developers overlook until they hit errors: the subrequest budget.

If your Hydrogen app makes too many API calls during a server-side render (SSR), Oxygen will reject the request. That’s not a bug — it’s by design. Subrequest budgets keep storefronts fast, stable, and cost-effective at scale.

What is a Subrequest Budget?

  • A subrequest = any outgoing request your server-side function makes during SSR.
  • This includes Shopify Storefront API calls, third-party API calls, or even internal fetches.
  • Oxygen enforces a limit per request (budget) to ensure no single page overwhelms the edge runtime.

Why Shopify Uses Subrequest Budgets

  1. Performance Protection
    • Prevents runaway SSR that slows down tail latency (p95/p99).
  2. Cost Control
    • API calls = real infrastructure costs. Shopify limits abuse for fairness.
  3. Consistency Across Stores
    • Ensures all merchants get reliable edge performance, not just those with optimized teams.

Typical Budget Limits (2025)

  • Default Budget: ~50 subrequests per page render.
  • Soft Failures: Logs warnings as you approach budget.
  • Hard Failures: Requests above the limit are rejected.

(Exact limits may vary by plan — Plus merchants may have higher ceilings.)

How to Debug Subrequest Overages

  1. Use the Subrequest Profiler
    • Available in Shopify CLI.
    • Shows how many requests each page consumes and which ones are slow.
  2. Trace API Dependencies
    • GraphQL queries often balloon into multiple subrequests if not consolidated.
  3. Log Requests in CI/CD
    • Integrate budget checks into pipelines to catch regressions before deploy.

Best Practices for Staying Within Budget

  • Batch GraphQL Queries: Request all needed fields in one query instead of chaining.
  • Cache Responses: Use CDN or session caching for repeat queries.
  • Preload Common Data: Inject shared data (e.g., navigation, footer) once, not per component.
  • Defer Non-Critical Calls: Lazy-load recommendations or personalization client-side.
  • Monitor in Production: Tail latency spikes often come from budget overages.

Case Example

  • A merchant with dynamic bundles was hitting 100+ subrequests per render.
  • After consolidating queries + caching, they cut it to 20 subrequests.
  • Result: 50% drop in p99 latency, no more Oxygen hard failures.

Future Outlook

  • Shopify is expanding observability tooling for subrequest usage.
  • Expect per-component subrequest budgets in future Hydrogen updates.
  • AI query optimizers may eventually consolidate GraphQL calls automatically.

Conclusion

Subrequest budgets aren’t a limitation — they’re a performance guarantee. Shopify merchants who understand and design around them get faster, more reliable Oxygen storefronts with lower costs.

Treat subrequest profiling as part of your CI/CD flow, not as an afterthought.

Posted in Blog

About nuwudorder