zuora-order-migration-build

Files (1)

• SKILL.md

SKILL.md (first lines)

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 generating Order API implementation code by converting customer integration code from Subscription/Amendment API and Subscribe Action API. The Subscribe Action API supports two distinct modes (preview vs create) which map to different Order API endpoints. The user should have a migration plan (from `/zuora-order-migration-design`) or provide their source code directly.

## Input

The user's request: $ARGUMENTS

This could be:
- Customer source code file paths
- Reference to a migration plan document
- Specific operations to convert (cancel, suspend, resume, renew, create, update)

## Tool routing

Use local file reads and edits for conversion work, bundled mapping references for known S/A-to-Order transformations, and `mcp__zuora-mcp__zuora_codegen` for exact Order API endpoint/model details. Use subscription MCP tools only for their specific create/cancel/renew operations when validation requires them. `mcp__zuora-mcp__ask_zuora` is allowed only as a fallback for a specific Order API capability or migration-tradeoff question that remains after references and codegen are checked. If business intent is ambiguous, ask the user to confirm the mapping.

## Workflow

**⚠️ CRITICAL PRINCIPLE: Always Modify Existing Files**

When converting customer integration code:
- ✅ DO: Use Edit tool to modify existing customer files in-place
- ✅ DO: Comment out old code and add converted code in the same location
- ✅ DO: Create clear BEFORE/AFTER markers in the same file
- ❌ DON'T: Create new files like `*_converted.py` or `*_order_api.py`
- ❌ DON'T: Use Write tool for existing integration files

**Why:** PR reviews need to see the diff between old and new code. New files hide the changes and make it impossible to review what actually changed.

**Exception:** New supporting files (validation scripts, checklists, documentation) can be created with Write tool since they don't replace existing code.

### Step 1: Review Context

**If migration plan exists:**
- Read the migration plan to understand:
  - Which S/A API calls were detected
  - The field mappings for each operation
  - Programming language used
  - Edge cases identified

**If no plan exists:**
- Read the customer's source code files
- Identify the programming language
- Detect API patterns (Subscription, Amendment, Subscribe Action)
- Recommend running `/zuora-order-migration-design` first for comprehensive analysis

### Step 2: Read Reference Mappings

For each operation being converted, read the corresponding reference document from `${CLAUDE_PLUGIN_ROOT}/references/`:

**Available Reference Mappings:**

1. **Subscription Cancel** → `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-cancel-api-mapping.md`
2. **Subscription Suspend** → `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-suspend-api-mapping.md`
3. **Subscription Resume** → `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-resume-api-mapping.md`
4. **Subscription Renew** → `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-renew-api-mapping.md`
5. **Subscription Create** → `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-create-api-mapping.md`
6. **Subscription Update** → `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-update-api-mapping.md`
7. **Subscribe Action** → `${CLAUDE_PLUGIN_ROOT}/references/action-subscribe-api-mapping.md`
   - **Note**: Subscribe API supports two modes (preview vs create) controlled by `PreviewOptions`
   - **Preview mode** (PreviewOptions present) → `/v1/orders/preview` with `previewAccountInfo`
   - **Create mode** (PreviewOptions absent) → `/v1/orders` with `newAccount` or `existingAccountNumber`
   - See "Subscribe API: Preview vs Create Mode Detection" in Step 4 for complete handling

These documents provide field-accurate mappings verified against Zuora Billing source code.

### Step 3: Generate Converted Code

For each API call in the customer's code (Subscription, Amendment, or Subscribe Action), generate the Order API equivalent following these guidelines:

#### Code Generation Guidelines

**CRITICAL: Always Modify Existing Files, Never Create New Files**

**Why:** When converting integration code, changes must be visible in PR diffs. Creating new files makes it impossible to see what changed from the original code. Always use the Edit tool to modify existing customer files directly.

**How:**
1. Read the existing customer file first
2. Locate the exact S/A API code to convert
3. Use Edit tool to replace the old code with converted code in-place
4. Keep commented BEFORE/AFTER blocks to show the transformation
5. Preserve all surrounding code unchanged

**1. Preserve Structure**
- Keep similar code organization and flow
- Maintain the same variable names where possible
- Preserve error handling patterns
- Keep the same file and function names

**2. Match Coding Style**
- Use same indentation (spaces vs tabs)
- Follow same naming conventions
- Maintain consistent formatting
- Match the customer's code style exactly

**3. Add Explanatory Comments**
- Mark the original S/A API code with "BEFORE" comment (keep original as comment)
- Mark the new Order API code with "AFTER" comment
- Explain what changed and why
- Reference the field mapping source
- This creates clear before/after comparison in PR diff

**4. Include TODO Markers**
- Mark areas requiring customer input (account numbers, dates, etc.)
- Highlight new required fields that don't have obvious sources
- Flag response handling changes that need attention

**5. Update Response Handling**
- Show old response structure vs new (as comments)
- Update field extraction code
- Handle new response fields (`orderNumber`, nested structures)

**6. Add Error Handling**
- Include Order API specific error handling
- Handle validation errors from new required fields
- Add transaction-level error handling

From zuora/zuora-coding-agent, MIT.

More from zuora/zuora-coding-agent