Update to Zuora Coding Agent

{
  "description": "Analyze customer code and produce Order API migration plan with field-accurate mappings",
  "included_files": [],
  "name": "zuora-order-migration-design",
  "skill_md_contents": "---\nname: zuora-order-migration-design\ndescription: Analyze customer code and produce Order API migration plan with field-accurate mappings\nargument-hint: [customer code file paths or migration requirements]\nallowed-tools: [Read, Write, Glob, Grep, Bash, Agent, mcp__zuora-mcp__ask_zuora, mcp__zuora-mcp__query_objects, mcp__zuora-mcp__zuora_codegen, mcp__zuora-mcp__get_account_summary]\n---\n\nCodex-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/`.\n\n\nYou are analyzing customer integration code and producing an Order API migration plan. This migration moves subscription management from legacy Subscription/Amendment API and Subscribe Action API to the Order API, which provides a unified, action-based model.\n\n## Input\n\nThe user's migration context: $ARGUMENTS\n\nThis could be:\n- Customer source code file paths\n- Code snippets pasted directly\n- Description of their current integration approach\n- Tenant context for data-driven analysis\n\n## Tool routing\n\nUse local code reads and bundled Order/Amendment mapping references for endpoint inventory, field mappings, and migration-plan structure. Use `mcp__zuora-mcp__zuora_codegen` for exact Order API endpoint/model requirements, `mcp__zuora-mcp__query_objects` / `mcp__zuora-mcp__get_account_summary` for tenant state, and `mcp__zuora-mcp__ask_zuora` only when a specific Order API capability, limitation, or migration tradeoff remains unresolved after those sources.\n\n## Workflow\n\n### Step 1: Analyze Customer Code\n\nIf the user provides source code:\n\n**1.1 Read the provided code**\n- Use Read tool for file paths\n- Accept code snippets directly\n\n**1.2 Identify programming language**\n- Python, Java, JavaScript/Node.js, Ruby, C#, PHP, etc.\n\n**1.3 Detect Subscription/Amendment/Subscribe API patterns**\n\nLook for these endpoint patterns:\n\n**Python indicators:**\n```python\n# Subscription API\nrequests.post(\"*/v1/subscriptions\")\nrequests.put(\"*/v1/subscriptions/*\")\nrequests.put(\"*/v1/subscriptions/*/cancel\")\nrequests.put(\"*/v1/subscriptions/*/suspend\")\nrequests.put(\"*/v1/subscriptions/*/resume\")\nrequests.put(\"*/v1/subscriptions/*/renew\")\nrequests.post(\"*/v1/amendments\")\n\n# Subscribe Action API\nrequests.post(\"*/v1/action/subscribe\")\n```\n\n**Java indicators:**\n```java\nHttpPost(\"/v1/subscriptions\")\nHttpPut(\"/v1/subscriptions/\")\nnew URI(\"*/v1/amendments\")\nHttpPost(\"/v1/action/subscribe\")  // Subscribe Action API\n```\n\n**JavaScript/Node.js indicators:**\n```javascript\nfetch('*/v1/subscriptions', {method: 'POST'})\nfetch('*/v1/subscriptions/*', {method: 'PUT'})\naxios.post('*/v1/subscriptions')\nfetch('*/v1/action/subscribe', {method: 'POST'})  // Subscribe Action API\naxios.post('*/v1/action/subscribe')               // Subscribe Action API\n```\n\n**1.4 Catalog each API call**\n- File name and line number\n- API endpoint and HTTP method\n- Request payload structure\n- Response handling code\n- For Subscribe API: Detect if creating new account or using existing account\n\n**Output:** Table of detected API calls with context\n\n### Step 2: Map to Order API Equivalents\n\nFor each detected S/A API call, reference the verified mapping documents in `../references/`:\n\n**Available Reference Mappings:**\n\n1. **Subscription Cancel** → Read `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-cancel-api-mapping.md`\n   - Maps `PUT /v1/subscriptions/{key}/cancel` to Order API `CancelSubscription` action\n   - Verified against: `POSTSubscriptionCancellationMeta`, `PostOrderActionCancelMeta`\n\n2. **Subscription Suspend** → Read `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-suspend-api-mapping.md`\n   - Maps `PUT /v1/subscriptions/{key}/suspend` to Order API `Suspend` action\n   - Handle suspend with resume date (requires two actions: Suspend + Resume)\n   - Verified against: `PUTSubscriptionSuspendMeta`, `PostOrderActionSuspendMeta`\n\n3. **Subscription Resume** → Read `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-resume-api-mapping.md`\n   - Maps `PUT /v1/subscriptions/{key}/resume` to Order API `Resume` action\n   - Important: `extendsTerm` belongs in Resume action, not Suspend\n   - Verified against: `PUTSubscriptionResumeMeta`, `PostOrderActionResumeMeta`\n\n4. **Subscription Renew** → Read `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-renew-api-mapping.md`\n   - Maps `PUT /v1/subscriptions/{key}/renew` to Order API `RenewSubscription` action\n   - Important: Uses subscription's existing renewal term settings\n   - Verified against: `POSTSubscriptionRenewalMeta`, `PostOrderActionRenewSubscriptionMeta`\n\n5. **Subscription Create** → Read `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-create-api-mapping.md`\n   - Maps `POST /v1/subscriptions` to Order API `CreateSubscription` action\n   - Covers all charge models and term configurations\n\n6. **Subscription Update** → Read `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-update-api-mapping.md`\n   - Maps `PUT /v1/subscriptions/{key}` to appropriate Order API actions\n   - May involve multiple action types depending on the update\n\n7. **Subscribe Action** → Read `${CLAUDE_PLUGIN_ROOT}/references/action-subscribe-api-mapping.md`\n   - Maps `POST /v1/action/subscribe` to Order API `CreateSubscription` action\n   - Handles both new account creation and existing account scenarios\n   - Maps Account, BillToContact, SoldToContact, PaymentMethod to Order API equivalents\n   - Important: Payment methods can only be created for new accounts in Order API\n   - Verified against: `SubscribeMeta`, `PostOrderActionCreateSubscriptionMeta`\n\n**Output:** Mapping table showing each API call and its Order API equivalent\n\n### Step 3: Assess Tenant Context (if applicable)\n\nIf tenant is connected and user wants data-driven analysis:\n\n**3.1 Query current state**\n- Call `mcp__zuora-mcp__query_objects` to inspect:\n  - Subscription count, statuses, and term types\n  - Amendment history and patterns\n  - Rate plans and charge models in use\n  - Custom fields on subscriptions and amendments\n\n**3.2 Sample representative accounts**\n- Use `mcp__zuora-mcp__get_account_summary` for typical accounts\n- Understand subscription structures in production\n\n**3.3 Call Zuora knowledge base**\n- Call `mcp__zuora-mcp__ask_zuora` for unresolved Order API capability or best-practice questions; prefer checking the mapping references (Step 2) first when they are likely to have the answer. Skip this when local mappings already answer the issue.\n\n**Output:** Current state summary with statistics\n\n### Step 4: Identify Edge Cases and Risks\n\nBased on code analysis and tenant data:\n\n**Common edge cases:**\n- Mid-term amendments (changes mid-billing-period)\n- Future-dated amendments\n- Charge-level overrides (price, quantity, billing period)\n- Multi-product subscriptions\n- Custom field usage on subscription and amendment objects\n- Integration points that reference subscription or amendment IDs\n- Suspend with resume date (requires two Order API actions)\n- Error handling differences between APIs\n- Subscribe API with new account vs existing account detection\n- Payment method creation limitations (Order API only supports for new accounts)\n- Credit card field name changes (creditCardNumber → cardNumber)\n- Account and contact creation in Subscribe API → newAccount in Order API\n\n**Risk assessment:**\n- Breaking changes in response structure\n- New required fields in Order API\n- Processing option changes (`invoice`/`collect` → `processingOptions.runBilling`/`collect`)\n- Contract effective date → trigger dates transformation\n- Testing scope and sandbox requirements\n\n**Output:** Edge case list and risk matrix (likelihood, impact, mitigation)\n\n### Step 5: Generate Migration Plan Document\n\nProduce a comprehensive migration plan:\n\n```markdown\n# Order API Migration Plan\n\n**Generated:** {timestamp}\n**Customer Code Analyzed:** {file_count} files, {line_count} lines\n**Programming Language:** {language}\n\n## Executive Summary\n\n- **Total S/A API Calls Detected:** {count}\n- **Operations:** {operation types: create, cancel, suspend, resume, renew, update, amendments}\n- **Complexity:** {Low/Medium/High}\n- **Estimated Effort:** {hours/days based on operation count and complexity}\n\n### Why Migrate to Order API\n\n- **Atomic operations**: Multiple subscription changes in one transaction\n- **Future-dating**: Schedule changes in advance with precise control\n- **Unified model**: Consistent action-based structure for all operations\n- **Better error handling**: Transaction-level rollback\n- **Enhanced flexibility**: Support for complex subscription scenarios\n\n## Current State Assessment\n\n### Detected API Calls\n\n| File | Line | Current API | HTTP Method | Order API Equivalent |\n|------|------|-------------|-------------|---------------------|\n| customer_code.py | 45 | /v1/subscriptions/{key}/cancel | PUT | POST /v1/orders (CancelSubscription) |\n| ... | ... | ... | ... | ... |\n\n### Tenant Statistics (if available)\n\n- Subscription count: {count}\n- Active subscriptions: {count}\n- Common charge models: {flat fee, per unit, tiered, etc.}\n- Custom fields in use: {list}\n\n## Field Mappings by Operation\n\n[For each detected operation, include detailed field mapping from the reference documents]\n\n### Example: Subscription Cancel Mapping\n\n**Current Code (Subscription API):**\n```python\n# Line 45-52 in customer_code.py\nresponse = requests.put(\n    f\"https://rest.zuora.com/v1/subscriptions/{subscription_key}/cancel\",\n    json={\n        \"cancellationPolicy\": \"SpecificDate\",\n        \"cancellationEffectiveDate\": cancel_date\n    }\n)\n```\n\n**Order API Equivalent:**\n- Endpoint: `POST /v1/orders`\n- Action type: `CancelSubscription`\n- New required fields: `orderDate`, `existingAccountNumber`\n- Field transformations:\n  - `cancellationEffectiveDate` → both `triggerDates.triggerDate` and `cancelSubscription.cancellationEffectiveDate`\n  - `invoiceCollect` → `processingOptions.runBilling` and `processingOptions.collect`\n\n[Repeat for each operation]\n\n## Migration Phases\n\n### Phase 1: Code Migration\n- Rewrite subscription management code to use Order API\n- Update request/response handling\n- Add new required fields\n- Transform field names and structures\n\n### Phase 2: Sandbox Validation\n- Deploy to sandbox environment\n- Test all operations with sample data\n- Verify subscription state changes\n- Check billing/invoice generation\n\n### Phase 3: Integration Updates\n- Update downstream systems for Order API responses\n- Handle new field names (`orderNumber` vs `subscriptionId`)\n- Update error handling for new error formats\n\n### Phase 4: Parallel Run (if feasible)\n- Run both APIs side-by-side during transition\n- Compare results for validation\n- Monitor for discrepancies\n\n### Phase 5: Production Cutover\n- Deploy Order API code to production\n- Monitor initial transactions closely\n- Have rollback plan ready\n\n### Phase 6: Post-Migration Monitoring\n- Watch billing runs for anomalies\n- Monitor subscription changes\n- Track error rates\n- Gather customer feedback\n\n## Edge Case Analysis\n\n[For each identified edge case:]\n\n**Edge Case:** Suspend with resume date\n\n**Current Approach (S/A API):**\nSingle call with `resumeDate` field\n\n**Order API Approach:**\nRequires two separate actions in one order:\n1. `Suspend` action\n2. `Resume` action with `resumeSpecificDate`\n\n**Migration Impact:**\nCode must be refactored to create two action objects\n\n[Repeat for each edge case]\n\n## Risk Matrix\n\n| Risk | Likelihood | Impact | Mitigation |\n|------|-----------|--------|-----------|\n| Response parsing errors | High | Medium | Update all response handling code, add unit tests |\n| Missing required fields | Medium | High | Thorough code review, sandbox testing |\n| Integration breakage | Medium | High | Update integrations before cutover |\n| ... | ... | ... | ... |\n\n## Key Migration Principles\n\n### 1. Processing Options Move to Order Level\n- `invoice`/`collect`/`invoiceCollect` → `processingOptions.runBilling` and `processingOptions.collect`\n\n### 2. Subscription Number Moves to Request Body\n- No longer in URL path, now in request body under `subscriptions[].subscriptionNumber`\n\n### 3. Contract Effective Date → Trigger Dates\n- `contractEffectiveDate` → `triggerDates[{name: \"ContractEffective\", triggerDate: \"...\"}]`\n\n### 4. Action Type Must Be Explicit\n- Subscription API: implicit from endpoint (cancel, suspend, renew)\n- Order API: explicit `type` field in each action\n\n## Common Gotchas\n\n### ❌ Incorrect: Specifying Renewal Terms in Order API\nRenewal terms must be pre-configured on the subscription. Order API uses existing settings.\n\n### ✅ Correct: Order API Uses Subscription's Renewal Settings\n`RenewSubscription` action relies on subscription's renewal term configuration\n\n### ❌ Incorrect: extendsTerm in Suspend Action\n`extendsTerm` belongs in Resume action, not Suspend\n\n### ✅ Correct: extendsTerm in Resume Action\nWhen suspending with resume date, `extendsTerm` goes in the Resume action\n\n[Add more gotchas from reference documents]\n\n## Validation Checklist\n\n- [ ] All API calls identified and mapped (Subscription, Amendment, Subscribe Action)\n- [ ] Field mappings verified against reference documents\n- [ ] New required fields identified and sourced (orderDate, existingAccountNumber/newAccount)\n- [ ] Response handling updated for new structure\n- [ ] Error handling updated for new error formats\n- [ ] Integration points identified and migration planned\n- [ ] For Subscribe API: Identified if creating new or using existing accounts\n- [ ] For Subscribe API: Payment method handling strategy defined (Order API limitation for existing accounts)\n- [ ] Credit card field name changes handled (creditCardNumber → cardNumber)\n- [ ] Sandbox environment prepared with test data\n- [ ] Test cases written for all operations\n- [ ] Rollback plan documented\n\n## Next Steps\n\n1. Review this migration plan with your team\n2. Set up sandbox environment with Order API enabled\n3. Run `/zuora-order-migration-build [file-paths]` to generate converted code\n4. Execute sandbox testing\n5. Update integrations\n6. Plan production cutover\n\n## Resources\n\n- Order API reference mappings: \n  - Amendment APIs: `${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-*-api-mapping.md`\n  - Subscribe Action API: `${CLAUDE_PLUGIN_ROOT}/references/action-subscribe-api-mapping.md`\n- [Zuora Order API Documentation](https://www.zuora.com/developer/api-references/api/tag/Orders)\n- [Subscription API Documentation](https://www.zuora.com/developer/api-references/api/tag/Subscriptions)\n- [Subscribe Action API Documentation](https://developer.zuora.com/v1-api-reference/older-api/actions/action_postsubscribe)\n```\n\n**Output:** Complete migration plan document\n"
}