If you’ve been managing APIs in IBM API Connect for any length of time, you’ve probably encountered the situation where an application has active subscriptions against an older product version, and you need to move those subscriptions to a newer version without disrupting the consuming application. This has historically been a manual and sometimes error-prone process. API Connect v12 changes that — significantly.

In this article, I’ll walk you through what’s changed in v12 for subscription migration, how to identify subscriptions that need migration directly from the CMS Portal home screen, and a step-by-step walkthrough of the process itself.

Table of Contents

  1. Why Subscription Migration Matters
  2. What’s Changed in v12
  3. Identifying Subscriptions That Need Migration
  4. Step-by-Step Walkthrough
  5. CLI Approach
  6. IBM Documentation

Why Subscription Migration Matters

In API Connect, an application subscribes to a product plan, not directly to an API. When you publish a new version of a product, existing subscriptions against the old version remain active. For the consuming application to benefit from changes in the new version — whether that’s new API operations, updated rate limits, or modified scopes — you need to migrate those subscriptions.

Historically, this migration required either:

  • Asking each application owner to manually resubscribe (painful at scale)
  • Using undocumented REST calls against the Consumer API
  • Living with version drift between what consumers use and what you’ve published

v12 addresses this with a first-class migration workflow built directly into the CMS Portal.

What’s Changed in v12

API Connect v12 introduces a dedicated subscription migration UI within the CMS Portal. Key improvements include:

  • Portal Home Screen Visibility: A new “Subscriptions Requiring Migration” widget appears on the CMS Portal home screen, giving operators immediate visibility into subscriptions that are out of sync with the current published product versions.
  • Bulk Migration: You can migrate multiple subscriptions in a single operation.
  • Version Compatibility Checking: The system validates that the target plan is compatible before allowing migration.
  • Audit Trail: Every migration is recorded with the operator who performed it and the timestamp.

Identifying Subscriptions That Need Migration

From the CMS Portal home screen, look for the “Subscriptions Requiring Migration” panel. It shows you at a glance:

  • Application name
  • Current plan version subscribed to
  • Latest available version of that plan
  • Age of the subscription (how long it’s been out of date)

This dashboard view makes it trivial to spot which consumer organisations have stale subscriptions and prioritise outreach or bulk migration.

Step-by-Step Walkthrough

Via the CMS Portal UI

  1. Log in to your CMS Portal as an administrator.
  2. Navigate to the Home screen — you should see the “Subscriptions Requiring Migration” widget.
  3. Click on the widget to expand the full list.
  4. Select the subscriptions you want to migrate (or click “Select All” for bulk operations).
  5. Click Migrate Subscriptions.
  6. In the migration dialog, confirm the target version — the system pre-selects the latest compatible version.
  7. Click Confirm.
  8. Review the success/failure summary. Failed migrations will show the reason (e.g., incompatible plan structure).

Via the Consumer API

If you prefer automation, you can drive migration via the Consumer API. Here’s a representative example:

# First, list subscriptions that are out of date
curl -X GET \
  "https://${CATALOG_HOST}/consumer-api/subscriptions?state=out_of_sync" \
  -H "accept: application/json" \
  -H "authorization: Bearer ${TOKEN}"

# Migrate a specific subscription
curl -X POST \
  "https://${CATALOG_HOST}/consumer-api/subscriptions/${SUBSCRIPTION_ID}/migrate" \
  -H "accept: application/json" \
  -H "authorization: Bearer ${TOKEN}" \
  -H "content-type: application/json" \
  -d '{
    "targetPlanVersion": "2.0.0",
    "targetProductId": "abc123-versioned"
  }'

Via the APIC CLI

# Install the apic CLI plugin if needed
apic plugins:install apic-subscription-migration

# List out-of-sync subscriptions
apic subscriptions:list --catalog ${CATALOG_NAME} \
  --org ${PROVIDER_ORG} \
  --server ${MANAGEMENT_SERVER} \
  --state out_of_sync

# Migrate a subscription
apic subscriptions:migrate ${SUBSCRIPTION_ID} \
  --target-version 2.0.0 \
  --catalog ${CATALOG_NAME} \
  --org ${PROVIDER_ORG} \
  --server ${MANAGEMENT_SERVER}

CLI Approach

For operators managing large API ecosystems, the CLI is often the fastest path. Here’s a complete example checking and migrating subscriptions across a catalog:

# Environment variables
export MANAGE_SERVER="mgmt.example.com"
export CATALOG="sandbox"
export ORG="my-provider-org"

# Get all subscriptions needing migration
apic subscriptions:list \
  --server $MANAGE_SERVER \
  --catalog $CATALOG \
  --org $ORG \
  --fields id,app_id,plan_id,plan_version,state \
  --output - | jq '.[] | select(.state=="out_of_sync")'

# Bulk migrate (script)
for sub_id in $(apic subscriptions:list \
  --server $MANAGE_SERVER \
  --catalog $CATALOG \
  --org $ORG \
  --format json \
  --output - | jq -r '.[] | select(.state=="out_of_sync") | .id'); do
  echo "Migrating: $sub_id"
  apic subscriptions:migrate $sub_id \
    --server $MANAGE_SERVER \
    --catalog $CATALOG \
    --org $ORG
done

Best Practices

  • Always validate that the target plan has no breaking changes before migrating. Review the product’s API surface in the API Manager.
  • Communicate with application owners before migrating — some apps may depend on specific version behaviour.
  • Test in a non-production catalog first, especially if you’re scripting bulk migrations.
  • Review the migration report after bulk operations to identify any failures and investigate root causes.

IBM Documentation

For the official documentation on subscription migration in API Connect v12, see: https://www.ibm.com/docs/en/api-connect/software/12.1.1

Note: IBM docs links should be verified as they may be updated with new versions. The 12.1.1 link above was current at time of writing.

Summary

Subscription migration in API Connect v12 is now a first-class, auditable, operator-friendly operation. The CMS Portal home screen widget gives you immediate visibility, and the CLI support means you can automate it at scale. Whether you’re managing a handful of apps or hundreds, v12 makes it far easier to keep your consumer subscriptions in sync with your evolving API products.

Next steps: log into your v12 CMS Portal and check the home screen — you might be surprised how many subscriptions are quietly out of date.

Screenshots to Capture

  1. [Placeholder: /images/subscriptions-requiring-migration-widget.png] What to capture: The CMS Portal home screen showing the “Subscriptions Requiring Migration” widget with the list of out-of-sync subscriptions. Where: CMS Portal → Home screen (visible to operators immediately after login)

  2. [Placeholder: /images/subscription-migration-dialog.png] What to capture: The subscription migration confirmation dialog showing the target version pre-selection and migration confirmation button. Where: CMS Portal → Subscriptions Requiring Migration widget → Select subscriptions → Click “Migrate Subscriptions”

  3. [Placeholder: /images/subscription-migration-results-summary.png] What to capture: The post-migration results summary showing success/failure counts and any failed migrations with reasons. Where: CMS Portal → After clicking “Confirm” in the migration dialog

Have questions or tips of your own? Drop me a message on Twitter @cminion or open an issue on GitHub.