skills/zuora-api-design/SKILL.md

---
name: zuora-api-design
description: Propose the right Zuora API approach for a business requirement
argument-hint: <business requirement description>
allowed-tools: [Read, Glob, Grep, Bash, Agent, mcp__zuora-mcp__zuora_codegen, mcp__zuora-mcp__ask_zuora, mcp__zuora-mcp__query_objects]
---

Codex-only path resolution: When an instruction refers to `${CLAUDE_PLUGIN_ROOT}`, treat it as the root of this installed plugin. In Codex, resolve that root as the ancestor directory containing `skills/`, `references/`, and `.codex-plugin/`.


You are designing a Zuora API integration approach. The user has described a business requirement. Your job is to propose which Zuora APIs, objects, and patterns to use — NOT to generate code yet.

## Input

The user's business requirement: $ARGUMENTS

## Tool routing

Use `mcp__zuora-mcp__zuora_codegen` for endpoint discovery, request/response schemas, fields, enum values, SDK method details, and API-specific constraints. Use bundled references for integration patterns and general best practices. Use `mcp__zuora-mcp__ask_zuora` only if a product-behavior or business-process question remains after those sources are checked.

## Workflow

### Step 1: Clarify the requirement

If the user's description is ambiguous, ask targeted questions:
- What business outcome are they trying to achieve?
- What system is calling Zuora (backend service, frontend, batch job)?
- What Zuora objects are involved (accounts, subscriptions, invoices, payments)?
- What is the expected data volume and frequency?
- What programming language will be used?

### Step 2: Discover relevant APIs

Call `mcp__zuora-mcp__zuora_codegen` in this order:
1. `code_guidance` with language (default to `curl` if unknown) — understand SDK capabilities
2. `list_api_classes` — find relevant API groups
3. `get_class_apis` for the most relevant class(es) — see available endpoints
4. `get_api_details` for the most relevant endpoint(s) — get parameters, request/response shapes

### Step 3: Clarify domain questions

Call `mcp__zuora-mcp__ask_zuora` for unresolved product-level questions about Zuora Billing, Revenue, CPQ, or Payments behavior. Prefer checking endpoint specs (Step 2) and reference patterns (Step 5) first when they are likely to have the answer, but don't delay if the question is clearly qualitative. Skip this step when specs and references are sufficient.

### Step 4: Check existing data model

If the user has a connected Zuora tenant, use `mcp__zuora-mcp__query_objects` to inspect existing objects (accounts, subscriptions, products) and validate assumptions about the data model.

### Step 5: Read reference patterns

Read `${CLAUDE_PLUGIN_ROOT}/references/api-integration-patterns.md` for common patterns and anti-patterns. Read `${CLAUDE_PLUGIN_ROOT}/references/best-practices.md` for integration best practices.

### Step 6: Propose the design

Deliver a structured response:

- **Recommended APIs**: List of endpoints with purpose and HTTP method
- **Object model**: Which Zuora objects are read/written and their relationships
- **Call sequencing**: Order of API calls, dependencies, and data flow
- **Authentication**: OAuth client credentials approach, token caching
- **Error handling**: Retry strategy, idempotency, STOP_AND_CONFIRM handling
- **Pagination**: How to handle paginated responses (if listing/querying)
- **Risks and tradeoffs**: Rate limits, eventual consistency, known gotchas
- **Next step**: Suggest using `/zuora-api-build` to generate implementation code

Do NOT generate implementation code in this skill. Focus on design and approach selection.