Claude Code Subagent Patterns for E-Commerce Operations Teams

Anthropic's multi-agent coordination patterns guide from April 2026 describes five canonical topologies for deploying multiple Claude agents together. The one that ecommerce operations teams actually use most is the orchestrator-worker pattern: a coordinator spawns specialist subagents, each with a restricted tool set and a focused task, then synthesizes their outputs. The other four show up less often in production ecommerce settings than you'd expect from reading the docs.

We've deployed Claude Code subagent patterns for ecommerce operations across several Shopify and multi-channel merchants over the past six months. The three subagent patterns below are the ones that survived repeated production use. Several others didn't, and those failures are worth documenting as much as the successes.

Claude Code Subagent Patterns for Ecommerce Operations: The Architecture

Before the subagent patterns themselves, the architecture assumption that makes all of them work: each subagent definition is a Markdown file with YAML frontmatter stored in .claude/agents/ (project scope, version-controlled) or ~/.claude/agents/ (user scope). The frontmatter controls the model, the tools the subagent can call, and the permission mode. The orchestrator calls the Task tool to spawn a subagent, passing only the task prompt. The subagent returns a single final message. The parent context does not receive intermediate tool calls or raw tool output.

That last point matters for ecommerce operations work. A catalog audit touching 50,000 SKUs cannot fit in one agent's context window. An order reconciliation run spanning 3,000 line items from a peak sale period cannot either. These ecommerce subagent patterns force decomposition at the task boundary, which is exactly what bounded operational tasks need.

The ecommerce context we're working in: two Shopify Plus merchants. One runs approximately 8,000 active SKUs across three sales channels (Shopify, Amazon, a B2B wholesale portal). The other runs approximately 50,000 SKUs with daily catalog drift from supplier feeds. Both connect to downstream ERPs via custom connectors we maintain.

Pattern 1: Orchestrator and Specialist Workers for Catalog Validation

The business need. The 50,000-SKU merchant pulls daily product feed updates from four suppliers. About 2-3% of those updates carry bad data: missing variant weights, malformed Metafield values, prices that violate MAP agreements. The operations team was catching these problems reactively, after orders failed to fulfill or after MAP violation notices arrived. We needed a morning catalog audit that flagged violations before the store's traffic peak.

What broke first. A single Claude Sonnet 4.6 agent with Bash access to the Shopify Admin GraphQL API hit context exhaustion after roughly 3,000 product checks. It ran fine on low-SKU days, then silently produced incomplete output on days when supplier feeds were large. The output looked complete because the agent summarized confidently either way. We didn't catch the silent truncation until we noticed all flagged violations clustering in the first 3,000 products alphabetically.

That's the failure mode that pushed us toward subagent patterns for ecommerce operations: not crashes, but confident-looking wrong output.

The failure mode that pushed us toward subagent patterns: not crashes, but confident-looking wrong output.

What we built. Three specialist subagents running in parallel waves:

• catalog-reader: fetches product batches from Shopify Admin GraphQL API, returns structured JSON
• map-validator: receives a product batch, checks against a MAP rules config file, returns violations
• weight-validator: receives variant data, checks for missing or implausible weight values

Each specialist runs on Claude Haiku 4.5 with a restricted tool list. The orchestrator runs on Claude Sonnet 4.6 and handles batch decomposition and result synthesis. A batch is 200 products. For 50,000 SKUs that's 250 batches, processed in waves of 5 concurrent subagents.

# .claude/agents/map-validator.md
---
name: map-validator
description: "Validates product pricing against MAP rules. Receives product batch JSON, returns violations array. Use for any MAP compliance check."
model: claude-haiku-4-5-20251001
tools: [Read]
permissionMode: restricted
---
 
You receive a batch of Shopify product data as JSON and a MAP rules config path.
Check each product variant price against the MAP minimum for its vendor.
Return a JSON array of violations: { productId, variantId, currentPrice, mapFloor, vendor }.
Return an empty array if no violations found.
Return only valid JSON. No explanatory text.

The Read-only tool set is intentional. These subagents read files we've pre-staged from the API. They do not call external services themselves. The orchestrator owns all external calls and writes the staged files before spawning the worker wave.

// orchestrator/catalog-validation.ts
const productBatches = await stageBatchFiles(shopifyProducts, BATCH_SIZE);
 
const waveSize = 5;
const allViolations: Violation[] = [];
 
for (let i = 0; i < productBatches.length; i += waveSize) {
  const wave = productBatches.slice(i, i + waveSize);
  const waveResults = await Promise.all(
    wave.map(batch =>
      runSubagent({
        agentName: 'map-validator',
        prompt: `Validate batch at ${batch.filePath}. MAP rules at ${MAP_RULES_PATH}.`,
      })
    )
  );
  allViolations.push(...waveResults.flatMap(r => r.violations ?? []));
}

What this enabled. The catalog validation subagent pattern completes in 18 minutes for 50,000 SKUs. The orchestrator produces a violations report that drops into a Slack channel at 7am. The team reviews and approves fixes before the 9am traffic peak. Before these subagent patterns for ecommerce operations, violations were caught reactively after they caused downstream fulfillment failures.

Pattern 2: Fan-Out with Dynamic Workflows for Post-Peak Order Reconciliation

The business need. After Diwali 2025, this merchant processed 11,000 orders in a 72-hour window. The ERP sync connector had a known race condition that occasionally wrote duplicate line items. Finding the duplicates meant cross-referencing Shopify order records against ERP entries.

What broke. A single-agent reconciliation run for 11,000 orders took 4+ hours and hit Shopify's REST API rate limit partway through. After the rate limit hit, the agent's output became unreliable: it skipped orders to stay within what it calculated as the remaining safe calls. The final duplicate count was off by a factor of 3.

Sequential order checking at scale is the wrong architecture. Subagent patterns for ecommerce operations post-peak reconciliation should fan out, not run single-threaded.

What we built. An orchestrator that uses Dynamic Workflows (released in Claude Code in June 2026) to fan out parallel subagents across order batches. Each batch-level subagent gets its own Shopify API rate limit budget:

// orchestrator/reconcile-orders.ts
const orderIds = await fetchOrderIdList(startDate, endDate);
const batches = chunk(orderIds, 100);
 
const results = await Promise.all(
  batches.map(batch =>
    runSubagent({
      prompt: buildReconcilePrompt(batch),
      tools: ['Bash', 'Read'],
      model: 'claude-haiku-4-5-20251001',
      background: true,
    })
  )
);
 
const allDuplicates = results.flatMap(r => r.duplicates ?? []);
const reconciled = deduplicateByOrderId(allDuplicates);
await writeReconciliationReport(reconciled);

Each subagent runs in background mode. In background mode, any tool call that would trigger a permission prompt is auto-denied rather than blocking the session. The subagent continues without the tool.

That behavior is what makes the background mode ecommerce operations subagent pattern reliable at scale: no session blocking. But it's also the most dangerous failure mode.

A grader subagent validates the output from each batch before the orchestrator accepts it. The grader checks that the returned JSON is well-formed and that the order count in the response matches the batch size passed in. Any batch that fails the grader's check gets re-queued.

What this enabled. The fan-out subagent pattern for order reconciliation dropped the 11,000-order run from 4+ hours to 22 minutes. The rate limit problem disappeared entirely: batching to 100 orders per subagent kept each subagent's call volume well under the per-second budget. The grader subagent pattern caught 4 malformed responses in the first production run, all from edge-case orders with non-standard currency fields.

Pattern 3: Background Agents for Continuous Inventory Monitoring

The business need. The 8,000-SKU multi-channel merchant sells perishable goods with shelf-life constraints. A SKU going out of stock on Amazon while showing available on Shopify creates orders that can't fulfill. The operations team needed near-continuous inventory checks without blocking their Claude Code development sessions.

What broke. Running the inventory check as a foreground subagent every 30 minutes meant the engineer running the session couldn't do other work during the check. Any interactive permission prompt during the check blocked both the monitoring job and the engineer's session. Background mode with the right tool pre-approvals was the fix.

What we built. The background monitoring subagent pattern uses a read-restricted subagent with a polling loop managed by the orchestrator:

# .claude/agents/inventory-monitor.md
---
name: inventory-monitor
description: "Checks inventory levels across Shopify and Amazon SP-API. Returns SKUs below reorder threshold. Use for scheduled inventory checks."
model: claude-haiku-4-5-20251001
tools: [Bash, Read]
permissionMode: restricted
---
 
Check current inventory levels for all active SKUs.
Compare Shopify available quantity against Amazon FBA reserved quantity.
Flag any SKU where Shopify shows >0 and Amazon FBA shows 0 or null.
Return JSON: { flagged: [{ sku, shopifyQty, amazonQty, lastSync }] }
Write output to /tmp/inventory-check-{timestamp}.json.

The orchestrator spawns this as a background agent every 30 minutes, then polls the output file path:

// orchestrator/inventory-loop.ts
async function runInventoryCheck() {
  const timestamp = Date.now();
  const outputPath = `/tmp/inventory-check-${timestamp}.json`;
 
  await runSubagent({
    agentName: 'inventory-monitor',
    prompt: `Run inventory check. Write output to ${outputPath}.`,
    background: true,
  });
 
  await pollForFile(outputPath, { timeoutMs: 5 * 60 * 1000 });
  const result = JSON.parse(await readFile(outputPath, 'utf-8'));
 
  if (result.flagged.length > ALERT_THRESHOLD) {
    await sendSlackAlert(result.flagged);
  }
}

The silent failure in the first version. The first inventory monitor definition listed only Read in the tool list. The Amazon SP-API calls required Bash to execute a shell wrapper. In background mode, those Bash calls were auto-denied. The subagent compared Shopify inventory against an empty Amazon dataset and reported zero discrepancies on every run. It produced plausible-looking output for two days before we noticed no alerts had fired during a period we knew had stockouts.

We added Bash to the tool list. Alerts started firing within the hour.

Two days of false-green inventory monitoring is the concrete cost of not validating a subagent's tool list before deploying background subagent patterns. The git commit history on the .claude/agents/inventory-monitor.md file now shows that fix.

Model Routing and Token Cost Control

Running ecommerce operations subagent patterns at any real scale requires attention to model routing. Each subagent runs with its own full context window. The token cost multiplier for parallel subagent workloads is approximately 7x versus a single-threaded session running the same work. That's the cost of parallel context isolation in subagent patterns.

The routing model the three subagent patterns above settled on:

Haiku routing for worker subagents cuts per-run cost by approximately 60-70% for validation-heavy subagent patterns. The orchestrator stays on Sonnet because synthesis errors (missed edge cases, wrong deduplication logic) cost more in downstream rework than the model cost difference.

Beyond 5 concurrent subagents, the orchestrator's synthesis step becomes the bottleneck. For the 250-batch catalog run, we process in waves of 5, not all 250 in parallel. The total wall-clock time difference is under 4 minutes. The orchestrator's result merging stays reliable.

This is the same reason the building harnesses for operational AI agents architecture keeps the coordinator lightweight: a coordinator that's doing heavy reasoning can't also be merging 250 subagent outputs without degrading on one or the other.

What the Claude Code Subagent Patterns Delivered for Ecommerce Operations

• Catalog validation subagent pattern: 50,000-SKU morning audit in 18 minutes, catching MAP violations and weight anomalies before the 9am traffic peak
• Post-peak reconciliation subagent pattern: 11,000-order duplicate check from 4+ hours to 22 minutes, with reliable output across the full order set (grader subagent caught 4 malformed responses in the first run)
• Background monitoring subagent pattern: inventory check every 30 minutes without blocking engineer sessions; false-green monitoring eliminated after the tool-list fix
• Cost containment across all subagent patterns: Haiku routing for specialist workers reduced per-run cost by approximately 65% versus running all agents on Sonnet
• Infrastructure: Railway for the orchestrator process, Vercel for the violations dashboard that surfaces morning audit results

These are operational hygiene tasks, not transformational business outcomes. Catalog validation and order reconciliation exist in every ecommerce operation. The subagent patterns make them fast and reliable enough to run automatically. That's the actual value.

Observations

What worked

Model routing by task type made the biggest practical difference across all three subagent patterns. The initial version ran everything on Sonnet because we didn't trust Haiku for production data work. Once we restricted worker tasks to well-defined input/output contracts (receive batch, return structured JSON), Haiku's accuracy on format validation and pattern-matching tasks was indistinguishable from Sonnet.

The .claude/agents/ YAML definition format is more useful than it looks in the docs. Having the subagent definition version-controlled with the project means the tool list, model, and permission mode are auditable. When a silent failure happens (it will), you can check git history to see if someone modified the tool list. The inventory monitor failure was visible in commit history.

The grader subagent pattern, even when simple (just schema validation), caught malformed outputs that the orchestrator would otherwise have accepted. We added it too late in two of the three patterns. It should be the first thing built, not the last.

What didn't

The first version of the fan-out reconciliation pattern used foreground subagents for all batches in parallel. The context window multiplication was fine. What wasn't fine was the interactive permission prompt behavior: the orchestrator's session blocked on the first prompt from any subagent, and all other subagents queued behind it. The whole run serialized on one permission request.

Background mode with pre-approved tool sets is the correct default for ecommerce operations subagent patterns that run in batch or scheduled contexts.

A June 2026 benchmark paper evaluated LLM agents on long-horizon retail operations: 180-day simulations covering pricing, replenishment, supplier selection, and cash-flow management (RetailBench, arXiv:2606.15862). All tested agents fell substantially behind the oracle policy in net worth outcomes. Root cause: agents handled individual decisions well but couldn't maintain consistent policy across weeks. We saw the same pattern in an early attempt to build a replenishment planning agent. It produced good individual order recommendations but drifted from inventory targets without human course-correction every few days.

Subagent patterns for ecommerce operations work well for bounded, repeatable tasks with clear inputs and outputs. They don't solve long-horizon planning. The RetailBench results suggest that limitation isn't implementation-specific.

What we'd do differently

Validate a subagent's tool list against a sample task in foreground mode before deploying in background mode. The inventory monitor failure cost two days because we skipped that step. Now we run a 10-record validation pass in foreground mode before any background deployment.

Add a grader subagent on day one, not week three. Dynamic Workflows supports a grader that evaluates output against a rubric and sends workers back for revision. For ecommerce operations subagent patterns doing catalog or order work, a grader checking that returned JSON is well-formed and that record counts match expectations catches edge cases that slip through in early runs.

For the idempotency patterns that complement these ecommerce operations subagent patterns, see idempotent AI agents: retry-safe architecture for ecommerce.

References

1. Anthropic. "Multi-agent coordination patterns: Five approaches and when to use them." April 2026. https://claude.com/blog/multi-agent-coordination-patterns
2. Anthropic. "How we built our multi-agent research system." 2026. https://www.anthropic.com/engineering/multi-agent-research-system
3. Anthropic. "Create custom subagents." Claude Code documentation. https://code.claude.com/docs/en/sub-agents
4. Anthropic. "Orchestrate subagents at scale with dynamic workflows." Claude Code documentation. https://code.claude.com/docs/en/workflows
5. Li, et al. "RetailBench: A Data-Grounded Simulation Benchmark for LLM Agents in Retail Operations." arXiv:2606.15862. June 2026. https://arxiv.org/abs/2606.15862
6. Alhena AI. "AI Agents for Ecommerce: 9 Use Cases Driving Sales in 2026." 2026. https://alhena.ai/blog/ai-agent-use-cases-transforming-ecommerce/

Stack: Claude Sonnet 4.6 as orchestrator, Claude Haiku 4.5 for specialist workers, TypeScript orchestration layer deployed on Railway, violations dashboard on Vercel. Shopify Admin GraphQL API for product and order data, Amazon SP-API for inventory sync.