Skip to main content
POST
Upgrade or downgrade the plan

Authorizations

X-Suby-Api-Key
string
header
required

Secret API key. sk_live_… (production) or sk_sandbox_… (sandbox).

Headers

Idempotency-Key
string

Optional key (≤255 chars, e.g. a UUID v4) making this POST safe to retry · the response is cached 24h and a retry with the SAME key replays it instead of re-executing. The same key with a different body → 422 IDEMPOTENCY_KEY_CONFLICT; a retry while the first is in flight → 409.

Maximum string length: 255
Example:

"5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04"

Path Parameters

id
string
required
Example:

"sub_abc123"

Body

application/json
productId
string
required

Target plan (recurring Product) id.

Example:

"pro_9m2k1x8s7d6f"

effective
enum<string>
default:auto

auto = upgrade now / downgrade at period end. now/period_end override the timing (a downgrade is always period-end).

Available options:
auto,
now,
period_end
proration
enum<string>
default:delta

delta charges the prorated price difference on an immediate upgrade; none swaps with no charge (applied: true).

Available options:
delta,
none
useCustomerPaymentMethod
boolean
default:true

Charge the instrument saved at the first cycle. A fresh method + card overrides it; false forces a fresh card.

method
enum<string>

Fresh-card upgrade only. Ignored for a downgrade or a free swap.

Available options:
CARD,
APPLE_PAY,
GOOGLE_PAY
card
object
successUrl
string<uri>

Return URL after a 3DS/redirect on the upgrade CIT.

cancelUrl
string<uri>

Response

Plan change accepted (pending · applied on the upgrade charge / at renewal)

success
boolean
required
Example:

true

data
object
required

Endpoint-specific payload.

message
string