request_migration

fn request_migration(env: Env, merchant: Address, old_plan_id: u64, new_plan_id: u64)

Initiates a migration from an old plan to a new plan. This sets the migration_target field on all active subscriptions under the old plan. Each subscriber must individually call accept_migration or reject_migration - the migration is never automatic.

Parameters

Name	Type	Description
`merchant`	`Address`	The merchant’s Stellar address. Must own both plans.
`old_plan_id`	`u64`	The plan ID to migrate subscribers from.
`new_plan_id`	`u64`	The plan ID to migrate subscribers to.

Authorization

merchant.require_auth();

The merchant must own both the old and new plans.

Return value

None (void).

Events emitted

Event	Topics	Data
`mig_req`	`old_plan_id`, `new_plan_id`	Migration details

Error cases

Code	Name	Description
11	`MerchantMismatch`	The old and new plans belong to different merchants.
7	`PlanInactive`	The new plan is not active.

Examples

SDK
Soroban CLI

import { VowenaClient, NETWORKS } from "@vowena/sdk";

const client = new VowenaClient({
  contractId: NETWORKS.mainnet.contractId,
  rpcUrl: NETWORKS.mainnet.rpcUrl,
  networkPassphrase: NETWORKS.mainnet.networkPassphrase,
});

// Migrate all subscribers from plan 1 to plan 2
const tx = await client.buildRequestMigration(
  "GMERCHANT...ADDR",   // Merchant's address
  1,                     // Old plan ID
  2                      // New plan ID
);

const signedXdr = await signTransaction(tx);
await client.submitTransaction(signedXdr);

soroban contract invoke \
  --id CONTRACT_ID \
  --network mainnet \
  --source MERCHANT_SECRET \
  -- \
  request_migration \
  --merchant GMERCHANT...ADDR \
  --old_plan_id 1 \
  --new_plan_id 2

Requesting a migration does not move anyone. It sets a pending flag on each subscription. Subscribers can continue to be billed on the old plan until they explicitly accept or reject. This ensures subscribers always have full control.

Migrations are the correct way to handle price changes that exceed the price_ceiling. Create a new plan with the new pricing, then request a migration. Subscribers who accept will get a new allowance set against the new ceiling.

Overview

Core

Management

Migrations

Read-only

Utilities

request_migration

Parameters

Authorization

Return value

Events emitted

Error cases

Examples

​Parameters

​Authorization

​Return value

​Events emitted

​Error cases

​Examples

Parameters

Authorization

Return value

Events emitted

Error cases

Examples