How Do I Migrate Users to New Subscription Terms in Piano?

Choose the Right Migration Method

Action Manager (Bulk Subscription Upgrade)

Use when you need to move many subscribers from a source term to a destination term and you can accept the bulk upgrade workflow (typically executing at renewal/end of billing period).

Best for:

• Moving cohorts to a new term at the end of the current billing period

• Moving from payment terms to dynamic terms (with proper period mapping)

• Large-scale, operationally simple migrations

Limitations:

• Does not process subscriptions in a grace period

• Not recommended for shared subscriptions (child access may not transfer)

• Progress may appear 0% until execution time (for end-of-period upgrades)

• Does not support selective transfers — all eligible users matching the criteria will be upgraded

API-Driven Term Change (POST /publisher/term/change/do)

Use when you need fine-grained control or have shared subscriptions to migrate.

Best for:

• Targeting a specific subset (e.g., phased rollout, % of users)

• Automations where you need detailed logging and error handling

• Upgrading or downgrading users between plan tiers (e.g., Monthly → Annual, Lite → Standard)

• Correcting a subscription assigned to the wrong resource

• Migrating custom terms or grant-access scenarios where a term reassignment is needed

Pre-Migration Checklist

The following checklist applies to any migration method.

1. Define source and destination terms

   • Confirm term IDs and verify configuration (price, periods, access resources).

   • If using Action Manager bulk upgrades, ensure the destination term is compatible.

   • For API migrations, verify eligibility in advance using GET /publisher/term/change/can.

2. Export/compile the user list

   • Include at minimum: uid (or emails you can resolve to uid), current term, and renewal/billing state.

3. Exclude ineligible users

   • Remove users with auto-renew disabled from bulk migrations unless you explicitly intend their new subscription to expire after one period.

   • Remove inactive/invalid users as needed.

4. Plan around billing dates

   • To avoid immediate charges and preserve renewal timing, schedule execution for end of current billing period (common best practice).

   • Be aware: if a renewal occurs before your scheduled migration executes, the user may renew on the old term/price for that cycle.

5. Check for pending payment states

   • Subscriptions with pending or unfinished payments may block API-driven migrations until those payments are resolved.

6. Review trial settings on the destination term

   • If Apply trial period for new customers only is enabled on the target term, migrating subscribers may be charged the full regular price rather than the trial rate. Adjust this setting if you want migrated users to receive the trial.

Recommended Action Manager Configuration (Bulk Upgrades)

When upgrading cohorts via Action Manager, these settings are commonly used to prevent billing/access surprises:

• Billing timing: Set to end of current billing period.

• Immediate access: Typically OFF (New access begins immediately unchecked). This reduces the risk of granting access changes earlier than intended.

• Auto-renew OFF users: Exclude them from the migration list.

• Upgrade emails: Consider disabling generic scheduling emails.

Progress Indicator Behavior

If you schedule upgrades to execute at the end of the billing period, the bulk upgrade progress can remain at 0% until execution time — even though you may have configured access behavior differently. This is expected.

Shared Subscriptions: Avoid Bulk Upgrades

Bulk subscription upgrades are not recommended for shared subscriptions because child accounts may not be carried over to the new subscription, which can cause child users to lose access.

For shared subscriptions, use the API term change endpoint so you can migrate the parent and child relationships appropriately in one operation.

Handling Grace Periods

• Action Manager bulk upgrades do not process subscriptions in a grace period.

  • Plan a follow-up migration after the grace period resolves (for example, run another cohort upgrade later to catch those accounts).

• Grace periods can also affect notification timing and the effective "next billing date" used for execution.

Email Notifications During Term Migrations

Key Behavior Change During Scheduled Migrations

If a subscriber is scheduled for a term change/migration, the standard renewal reminder email template:

• X days until dynamic subscription automatic renewal or X Days until auto-renewal

may not send as expected for that renewal window.

Instead, configure and enable X Days Until Pending Term Change Execution and set its offset to a few days before the scheduled execution date so subscribers receive a clear "your subscription is changing" notice.

Also review the following templates:

• Term change completed

• X Days after subscription starts

Using the API for Targeted Upgrades

Resolve Email to UID (If Needed)

Use POST /publisher/user/search with the following common parameters:

• aid

• api_token

• q=<EMAIL>

• has_conversion_term=true

• converted_terms=<TERM_ID_FROM>

(Optional) Verify Eligibility and Current Subscription

Before executing, confirm the target term is eligible for the migration:

• GET /publisher/term/change/can

Then verify the user's current subscription state:

• POST /publisher/subscription/stats

Execute the Term Change

Use POST /publisher/term/change/do with the following commonly required parameters:

• aid

• api_token

• uid

• subscription_from

• term_to

• billing_timing

• immediate_access

• Optional proration parameters: prorate_access, prorate_rate — see Billing and Proration Behavior below.

billing_timing values:

Operational best practices:

• Log each API response for audit and troubleshooting.

• Run a small pilot cohort before scaling.

• Plan your script with throttling and retries based on your API rate limits.

(Optional) Verify Migration Status

After initiating changes, verify the outcome via:

• GET /publisher/term/change/getSubscriptionUpgradeStatus

Billing and Proration Behavior (API Migrations)

When using the API, you have direct control over how and when billing changes take effect. Using billing_timing=1 is recommended for most migrations, as it schedules the move on the existing renewal date, minimizing customer confusion and preserving the expected billing cadence.

Proration parameters:

• prorate_access — applies the amount already paid toward the new term (useful for Monthly → Annual without re-charging the user)

• prorate_rate=0 — charges the full amount of the new term

• prorate_rate=1 — charges a prorated amount based on the billing date

immediate_access — set to true when you want the user's access to reflect the new term right away, even if billing changes are scheduled for a later date.

Common Pitfalls and Troubleshooting

Users Renew at the Old Price

Cause: The migration executes at end-of-period, but the user renews before the scheduled change.

Mitigation:

• Schedule migrations with enough lead time and align execution timing with billing cycles.

• Validate that all intended users are actually scheduled.

Subscriptions in Grace Period Aren't Upgraded

Cause: Bulk upgrades skip grace-period subscriptions.

Mitigation: Run a later follow-up migration after grace periods resolve.

Users with Auto-Renew OFF Included by Mistake

Behavior: Bulk upgrade can still migrate them; depending on term configuration, the resulting subscription may expire after one period or behave unexpectedly.

Mitigation: Exclude such users from the input list.

Shared Subscription Children Lose Access

Cause: Bulk upgrade does not reliably transfer child access.

Mitigation: Use POST /publisher/term/change/do for shared subscriptions.

Migration/Import Failures (Data Issues)

Common causes:

• User already has an overlapping active subscription.

• Invalid or missing payment method token.

Mitigation: Clean input data, resolve overlaps, and verify payment method validity before rerunning.

Users Without a Valid Payment Method

Behavior: Users without a valid payment method token (e.g., trial users) may fail charging attempts, placing them into grace behavior until payment is updated.

Mitigation: Identify and resolve payment method issues before migration, and plan customer communication accordingly.

Dashboard Upgrade UI Doesn't Show the Target Term

Cause: The dashboard enforces resource consistency and only displays terms matching the current subscription's resource.

Mitigation: Use POST /publisher/term/change/do via the API to transfer to the correct term/resource.

Unexpected Full-Price Charges During Migration

Cause: Apply trial period for new customers only is enabled on the target term, preventing migrated subscribers from receiving the trial rate.

Mitigation: Review and adjust trial settings on the destination term before migrating.

Rollback and Stopping Changes

• Completed bulk upgrades cannot be automatically rolled back. Reverting typically requires manually canceling and re-creating subscriptions (dashboard or API).

• If an upgrade is pending, you can cancel scheduled upgrades individually per user (Dashboard → User → Subscriptions → Cancel upgrade), or via API where available.

• While a user is awaiting a subscription change, they may be unable to change auto-renew status from the front end in My Account; cancel the pending upgrade to restore self-service changes.

• A bulk upgrade can be stopped to prevent scheduled upgrades from being applied to users who have not yet been updated.

Last updated: June 26, 2026