Skip to main content
POST
/
subscription
/
migration
Migrate a subscription to a new plan
curl --request POST \
  --url https://billing.funnelfox.com/{org_id}/v1/subscription/migration \
  --header 'Content-Type: application/json' \
  --header 'ff-secret-key: <api-key>' \
  --data '
{
  "subs_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "pp_ident": "<string>",
  "reason": "",
  "comment": "",
  "external_id": "<string>",
  "strategy": "price_prorate",
  "dry_run": false,
  "strict_mode": true
}
'
{
  "payment_result": {
    "failed_message_for_user": "<string>",
    "order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "charged_amount": 123,
  "subs_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "oneoff_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
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
​
charged_amount
​
subs_id
string<uuid> | null
​
oneoff_id
string<uuid> | null