Skip to main content
POST
Migrate a subscription to a new plan
Supports two migration strategies:
  • delayed_start - Schedules the new subscription to start when the customer’s already-paid time ends
  • price_prorate - Unused time is credited toward the new plan’s first payment
The response includes the migration_strategy field showing which strategy was actually applied.

Strict Mode

By default (strict_mode: true), if the requested strategy isn’t available, the API returns a 400 error. Set strict_mode: false to automatically switch to the alternative strategy when the selected one fails.

Additional Options

Use dry_run: true to preview charges without executing the migration. Supports migrations from subscription to subscription or subscription to lifetime purchases.

Authorizations

ff-secret-key
string
header
required

Secret key for FunnelFox Billing API. Required for all requests.

Path Parameters

org_id
string
required

Organization ID

Body

application/json
subs_id
string<uuid>
required
pp_ident
string
required

Unique identifier of the price point

Maximum string length: 256
Pattern: ^[-A-Za-z_0-9]{1,256}$
reason
string
default:""

Short reason code (e.g., "duplicate_payment", "unauthorized_charge")

Maximum string length: 256
comment
string
default:""

Human-readable comment or reference (e.g., support ticket link)

Maximum string length: 2048
external_id
string | null

Your unique identifier for the user

Maximum string length: 256
strategy
enum<string>
default:price_prorate
Available options:
price_prorate,
delayed_start
dry_run
boolean
default:false
strict_mode
boolean
default:true

Response

200 - application/json
migration_strategy
enum<string>
required
Available options:
price_prorate,
delayed_start
payment_result
CheckoutMigrationPaymentOut · object | null
charged_amount
subs_id
string<uuid> | null
oneoff_id
string<uuid> | null