zuora-order-migration-design

name	zuora-order-migration-design
description	Analyze customer code and produce Order API migration plan with field-accurate mappings
argument-hint	["customer code file paths or migration requirements"]
allowed-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"]

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 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.

Input

The user's migration context: $ARGUMENTS

This could be:

• Customer source code file paths
• Code snippets pasted directly
• Description of their current integration approach
• Tenant context for data-driven analysis

Tool routing

Use 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.

Workflow

Step 1: Analyze Customer Code

If the user provides source code:

1.1 Read the provided code

• Use Read tool for file paths
• Accept code snippets directly

1.2 Identify programming language

• Python, Java, JavaScript/Node.js, Ruby, C#, PHP, etc.

1.3 Detect Subscription/Amendment/Subscribe API patterns

Look for these endpoint patterns:

Python indicators:

# Subscription API
requests.post("*/v1/subscriptions")
requests.put("*/v1/subscriptions/*")
requests.put("*/v1/subscriptions/*/cancel")
requests.put("*/v1/subscriptions/*/suspend")
requests.put("*/v1/subscriptions/*/resume")
requests.put("*/v1/subscriptions/*/renew")
requests.post("*/v1/amendments")

# Subscribe Action API
requests.post("*/v1/action/subscribe")

Java indicators:

HttpPost("/v1/subscriptions")
HttpPut("/v1/subscriptions/")
new URI("*/v1/amendments")
HttpPost("/v1/action/subscribe")  // Subscribe Action API

JavaScript/Node.js indicators:

fetch('*/v1/subscriptions', {method: 'POST'})
fetch('*/v1/subscriptions/*', {method: 'PUT'})
axios.post('*/v1/subscriptions')
fetch('*/v1/action/subscribe', {method: 'POST'})  // Subscribe Action API
axios.post('*/v1/action/subscribe')               // Subscribe Action API

1.4 Catalog each API call

• File name and line number
• API endpoint and HTTP method
• Request payload structure
• Response handling code
• For Subscribe API: Detect if creating new account or using existing account

Output: Table of detected API calls with context

Step 2: Map to Order API Equivalents

For each detected S/A API call, reference the verified mapping documents in ../references/:

Available Reference Mappings:

1. Subscription Cancel → Read ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-cancel-api-mapping.md

   • Maps PUT /v1/subscriptions/{key}/cancel to Order API CancelSubscription action
   • Verified against: POSTSubscriptionCancellationMeta, PostOrderActionCancelMeta

2. Subscription Suspend → Read ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-suspend-api-mapping.md

   • Maps PUT /v1/subscriptions/{key}/suspend to Order API Suspend action
   • Handle suspend with resume date (requires two actions: Suspend + Resume)
   • Verified against: PUTSubscriptionSuspendMeta, PostOrderActionSuspendMeta

3. Subscription Resume → Read ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-resume-api-mapping.md

   • Maps PUT /v1/subscriptions/{key}/resume to Order API Resume action
   • Important: extendsTerm belongs in Resume action, not Suspend
   • Verified against: PUTSubscriptionResumeMeta, PostOrderActionResumeMeta

4. Subscription Renew → Read ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-renew-api-mapping.md

   • Maps PUT /v1/subscriptions/{key}/renew to Order API RenewSubscription action
   • Important: Uses subscription's existing renewal term settings
   • Verified against: POSTSubscriptionRenewalMeta, PostOrderActionRenewSubscriptionMeta

5. Subscription Create → Read ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-create-api-mapping.md

   • Maps POST /v1/subscriptions to Order API CreateSubscription action
   • Covers all charge models and term configurations

6. Subscription Update → Read ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-update-api-mapping.md

   • Maps PUT /v1/subscriptions/{key} to appropriate Order API actions
   • May involve multiple action types depending on the update

7. Subscribe Action → Read ${CLAUDE_PLUGIN_ROOT}/references/action-subscribe-api-mapping.md

   • Maps POST /v1/action/subscribe to Order API CreateSubscription action
   • Handles both new account creation and existing account scenarios
   • Maps Account, BillToContact, SoldToContact, PaymentMethod to Order API equivalents
   • Important: Payment methods can only be created for new accounts in Order API
   • Verified against: SubscribeMeta, PostOrderActionCreateSubscriptionMeta

Output: Mapping table showing each API call and its Order API equivalent

Step 3: Assess Tenant Context (if applicable)

If tenant is connected and user wants data-driven analysis:

3.1 Query current state

• Call mcp__zuora-mcp__query_objects to inspect:
  • Subscription count, statuses, and term types
  • Amendment history and patterns
  • Rate plans and charge models in use
  • Custom fields on subscriptions and amendments

3.2 Sample representative accounts

• Use mcp__zuora-mcp__get_account_summary for typical accounts
• Understand subscription structures in production

3.3 Call Zuora knowledge base

• 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.

Output: Current state summary with statistics

Step 4: Identify Edge Cases and Risks

Based on code analysis and tenant data:

Common edge cases:

• Mid-term amendments (changes mid-billing-period)
• Future-dated amendments
• Charge-level overrides (price, quantity, billing period)
• Multi-product subscriptions
• Custom field usage on subscription and amendment objects
• Integration points that reference subscription or amendment IDs
• Suspend with resume date (requires two Order API actions)
• Error handling differences between APIs
• Subscribe API with new account vs existing account detection
• Payment method creation limitations (Order API only supports for new accounts)
• Credit card field name changes (creditCardNumber → cardNumber)
• Account and contact creation in Subscribe API → newAccount in Order API

Risk assessment:

• Breaking changes in response structure
• New required fields in Order API
• Processing option changes (invoice/collect → processingOptions.runBilling/collect)
• Contract effective date → trigger dates transformation
• Testing scope and sandbox requirements

Output: Edge case list and risk matrix (likelihood, impact, mitigation)

Step 5: Generate Migration Plan Document

Produce a comprehensive migration plan:

# Order API Migration Plan

**Generated:** {timestamp}
**Customer Code Analyzed:** {file_count} files, {line_count} lines
**Programming Language:** {language}

## Executive Summary

- **Total S/A API Calls Detected:** {count}
- **Operations:** {operation types: create, cancel, suspend, resume, renew, update, amendments}
- **Complexity:** {Low/Medium/High}
- **Estimated Effort:** {hours/days based on operation count and complexity}

### Why Migrate to Order API

- **Atomic operations**: Multiple subscription changes in one transaction
- **Future-dating**: Schedule changes in advance with precise control
- **Unified model**: Consistent action-based structure for all operations
- **Better error handling**: Transaction-level rollback
- **Enhanced flexibility**: Support for complex subscription scenarios

## Current State Assessment

### Detected API Calls

| File | Line | Current API | HTTP Method | Order API Equivalent |
|------|------|-------------|-------------|---------------------|
| customer_code.py | 45 | /v1/subscriptions/{key}/cancel | PUT | POST /v1/orders (CancelSubscription) |
| ... | ... | ... | ... | ... |

### Tenant Statistics (if available)

- Subscription count: {count}
- Active subscriptions: {count}
- Common charge models: {flat fee, per unit, tiered, etc.}
- Custom fields in use: {list}

## Field Mappings by Operation

[For each detected operation, include detailed field mapping from the reference documents]

### Example: Subscription Cancel Mapping

**Current Code (Subscription API):**
```python
# Line 45-52 in customer_code.py
response = requests.put(
    f"https://rest.zuora.com/v1/subscriptions/{subscription_key}/cancel",
    json={
        "cancellationPolicy": "SpecificDate",
        "cancellationEffectiveDate": cancel_date
    }
)

Order API Equivalent:

• Endpoint: POST /v1/orders
• Action type: CancelSubscription
• New required fields: orderDate, existingAccountNumber
• Field transformations:
  • cancellationEffectiveDate → both triggerDates.triggerDate and cancelSubscription.cancellationEffectiveDate
  • invoiceCollect → processingOptions.runBilling and processingOptions.collect

[Repeat for each operation]

Migration Phases

Phase 1: Code Migration

• Rewrite subscription management code to use Order API
• Update request/response handling
• Add new required fields
• Transform field names and structures

Phase 2: Sandbox Validation

• Deploy to sandbox environment
• Test all operations with sample data
• Verify subscription state changes
• Check billing/invoice generation

Phase 3: Integration Updates

• Update downstream systems for Order API responses
• Handle new field names (orderNumber vs subscriptionId)
• Update error handling for new error formats

Phase 4: Parallel Run (if feasible)

• Run both APIs side-by-side during transition
• Compare results for validation
• Monitor for discrepancies

Phase 5: Production Cutover

• Deploy Order API code to production
• Monitor initial transactions closely
• Have rollback plan ready

Phase 6: Post-Migration Monitoring

• Watch billing runs for anomalies
• Monitor subscription changes
• Track error rates
• Gather customer feedback

Edge Case Analysis

[For each identified edge case:]

Edge Case: Suspend with resume date

Current Approach (S/A API): Single call with resumeDate field

Order API Approach: Requires two separate actions in one order:

1. Suspend action
2. Resume action with resumeSpecificDate

Migration Impact: Code must be refactored to create two action objects

[Repeat for each edge case]

Risk Matrix

Risk	Likelihood	Impact	Mitigation
Response parsing errors	High	Medium	Update all response handling code, add unit tests
Missing required fields	Medium	High	Thorough code review, sandbox testing
Integration breakage	Medium	High	Update integrations before cutover
...	...	...	...

Key Migration Principles

1. Processing Options Move to Order Level

• invoice/collect/invoiceCollect → processingOptions.runBilling and processingOptions.collect

2. Subscription Number Moves to Request Body

• No longer in URL path, now in request body under subscriptions[].subscriptionNumber

3. Contract Effective Date → Trigger Dates

• contractEffectiveDate → triggerDates[{name: "ContractEffective", triggerDate: "..."}]

4. Action Type Must Be Explicit

• Subscription API: implicit from endpoint (cancel, suspend, renew)
• Order API: explicit type field in each action

Common Gotchas

❌ Incorrect: Specifying Renewal Terms in Order API

Renewal terms must be pre-configured on the subscription. Order API uses existing settings.

✅ Correct: Order API Uses Subscription's Renewal Settings

RenewSubscription action relies on subscription's renewal term configuration

❌ Incorrect: extendsTerm in Suspend Action

extendsTerm belongs in Resume action, not Suspend

✅ Correct: extendsTerm in Resume Action

When suspending with resume date, extendsTerm goes in the Resume action

[Add more gotchas from reference documents]

Validation Checklist

• All API calls identified and mapped (Subscription, Amendment, Subscribe Action)
• Field mappings verified against reference documents
• New required fields identified and sourced (orderDate, existingAccountNumber/newAccount)
• Response handling updated for new structure
• Error handling updated for new error formats
• Integration points identified and migration planned
• For Subscribe API: Identified if creating new or using existing accounts
• For Subscribe API: Payment method handling strategy defined (Order API limitation for existing accounts)
• Credit card field name changes handled (creditCardNumber → cardNumber)
• Sandbox environment prepared with test data
• Test cases written for all operations
• Rollback plan documented

Next Steps

1. Review this migration plan with your team
2. Set up sandbox environment with Order API enabled
3. Run /zuora-order-migration-build [file-paths] to generate converted code
4. Execute sandbox testing
5. Update integrations
6. Plan production cutover

Resources

• Order API reference mappings:
  • Amendment APIs: ${CLAUDE_PLUGIN_ROOT}/references/amendment-rest-v1-*-api-mapping.md
  • Subscribe Action API: ${CLAUDE_PLUGIN_ROOT}/references/action-subscribe-api-mapping.md
• Zuora Order API Documentation
• Subscription API Documentation
• Subscribe Action API Documentation

**Output:** Complete migration plan document