> ## Documentation Index > Fetch the complete documentation index at: https://documentation.suby.fi/llms.txt > Use this file to discover all available pages before exploring further. # Upgrade or downgrade the plan > Switch the subscription to a different recurring Product (the "plan"). The direction is derived from the price. **Upgrade** (higher price) → applies immediately, customer-present. The customer does **not** have to re-enter a card: set `useCustomerPaymentMethod: true` to charge the instrument saved at the first cycle (a 3DS challenge still surfaces on-session if the issuer requires it), or pass `method` + `card.tokenizedInstrument` for a fresh token. Same cadence charges the prorated **difference** for the rest of the cycle; a different cadence (e.g. monthly → annual) charges the full new price and resets the billing anchor. The plan swaps when that charge **completes** — the response is `202` with `payment` (+ `checkout` when a 3DS/redirect action is needed) and `applied: false`; the swap is confirmed by a `subscription.updated` webhook. **Downgrade** (lower price) → scheduled for the period end (no charge, no card): the next renewal bills the lower price. `applied: false`. VAT (Merchant-of-Record) is recomputed on the target plan at charge time from the customer's billing country. The target plan must be ACTIVE, recurring, and share the current plan's **currency** (cadence may differ). ## OpenAPI ````yaml /v3-beta/api-reference/openapi.yaml post /v3/subscriptions/{id}/change-plan openapi: 3.1.0 info: title: Suby.fi Merchant API version: 3.0.0-beta description: > The **v3** public merchant API for Suby.fi. RESTful (plural, resource-oriented endpoints under the `/v3` prefix). Authenticate every request with your secret API key in the `X-Suby-Api-Key` header. - `sk_live_…` keys operate in **production** (real funds). - `sk_sandbox_…` keys operate in a fully simulated **sandbox** (test cards, Base Sepolia crypto, no real money). The environment is derived from the key prefix. All monetary amounts are **integer cents** (except `priceCents` on some read shapes, which is a string) — token amounts are strings in the smallest unit (sats / lamports / wei). Fees are basis points. contact: email: dev@suby.fi url: https://suby.fi servers: - url: https://api.beta.suby.fi description: Production + sandbox (environment selected by API key prefix) security: - ApiKeyAuth: [] tags: - name: Products description: Manage your product catalog (one-time and recurring). - name: Checkout description: >- Hosted checkout — signed session tokens (`cs_…`) plus branding and appearance settings. - name: Payments description: >- Create, capture, void, and retrieve one-time & off-session payments (card, APM, and crypto). - name: Subscriptions description: Start and cancel recurring subscriptions. - name: Customers description: First-class customer records with billing address. - name: Payment Methods description: >- Save a payment method to a customer and manage saved instruments for off-session charges. - name: Webhook Endpoints description: Register outbound webhook destinations and rotate signing secrets. - name: Analytics description: Org-wide revenue analytics. - name: Health description: Unauthenticated liveness probe. paths: /v3/subscriptions/{id}/change-plan: post: tags: - Subscriptions summary: Upgrade or downgrade the plan description: > Switch the subscription to a different recurring Product (the "plan"). The direction is derived from the price. **Upgrade** (higher price) → applies immediately, customer-present. The customer does **not** have to re-enter a card: set `useCustomerPaymentMethod: true` to charge the instrument saved at the first cycle (a 3DS challenge still surfaces on-session if the issuer requires it), or pass `method` + `card.tokenizedInstrument` for a fresh token. Same cadence charges the prorated **difference** for the rest of the cycle; a different cadence (e.g. monthly → annual) charges the full new price and resets the billing anchor. The plan swaps when that charge **completes** — the response is `202` with `payment` (+ `checkout` when a 3DS/redirect action is needed) and `applied: false`; the swap is confirmed by a `subscription.updated` webhook. **Downgrade** (lower price) → scheduled for the period end (no charge, no card): the next renewal bills the lower price. `applied: false`. VAT (Merchant-of-Record) is recomputed on the target plan at charge time from the customer's billing country. The target plan must be ACTIVE, recurring, and share the current plan's **currency** (cadence may differ). operationId: changeSubscriptionPlan parameters: - $ref: '#/components/parameters/SubscriptionId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: type: object required: - productId properties: productId: type: string description: Target plan (recurring Product) id. example: pro_9m2k1x8s7d6f effective: type: string enum: - auto - now - period_end default: auto description: >- `auto` = upgrade now / downgrade at period end. `now`/`period_end` override the timing (a downgrade is always period-end). proration: type: string enum: - delta - none default: delta description: >- `delta` charges the prorated price difference on an immediate upgrade; `none` swaps with no charge (`applied: true`). useCustomerPaymentMethod: type: boolean default: true description: >- Upgrade (DEFAULT true): charge the instrument SAVED at the first cycle (no card re-entry; 3DS surfaces on-session if the issuer challenges). Passing a fresh `method` + `card` overrides it; set `false` to force a fresh card. method: type: string enum: - CARD - APPLE_PAY - GOOGLE_PAY description: >- Fresh-card upgrade only (when `useCustomerPaymentMethod` is not set). Ignored for a downgrade / free swap. card: type: object properties: tokenizedInstrument: type: string description: >- Fresh PSP card token (customer-present). Required for a fresh-card upgrade with a charge. successUrl: type: string format: uri description: Return URL after a 3DS/redirect on the upgrade CIT. cancelUrl: type: string format: uri responses: '202': description: >- Plan change accepted (pending — applied on the upgrade charge / at renewal) content: application/json: schema: allOf: - $ref: '#/components/schemas/SuccessEnvelope' - properties: data: type: object properties: subscription: $ref: '#/components/schemas/Subscription' scheduledChange: $ref: '#/components/schemas/ScheduledChange' applied: type: boolean description: >- `true` only for a no-charge `proration:"none"` upgrade (swapped inline). Otherwise `false` — the swap applies on the upgrade charge's completion or at the next renewal. payment: allOf: - $ref: '#/components/schemas/Payment' description: >- The upgrade CIT charge (upgrade with a charge only). checkout: type: object description: >- Customer-action handle for the upgrade CIT (3DS / redirect), when needed. properties: providerPaymentId: type: string threeDsChallengeUrl: type: string redirectUrl: type: string clientSecret: type: string '401': $ref: '#/components/responses/Unauthorized' '404': description: >- Subscription or target plan not found (`SUBSCRIPTION_NOT_FOUND`, `TARGET_PRODUCT_NOT_FOUND`) content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Target is the current plan (`SAME_PLAN`) content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- Not modifiable / incompatible target / missing card (`SUBSCRIPTION_NOT_MODIFIABLE`, `TARGET_PRODUCT_NOT_RECURRING`, `PLAN_CHANGE_CURRENCY_MISMATCH`, `UPGRADE_REQUIRES_CARD`, `PLAN_CHANGE_DECLINED`) content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: SubscriptionId: name: id in: path required: true schema: type: string example: sub_abc123 IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional key (≤255 chars, e.g. a UUID v4) that makes this POST safe to retry: the first request executes and its response is cached for 24h; a retry with the SAME key replays that response instead of re-executing (no duplicate payment/subscription). A reused key with a different request → `422 IDEMPOTENCY_KEY_CONFLICT`; a retry while the first is still in flight → `409`. See the Idempotency guide. schema: type: string maxLength: 255 example: 5f3b9c2e-1a4d-4f2b-9c31-7e2a1b6d8c04 schemas: SuccessEnvelope: type: object required: - success - data properties: success: type: boolean example: true message: type: string data: description: Endpoint-specific payload. Subscription: type: object properties: id: type: string example: sub_abc123 organizationId: type: string customerId: type: string productId: type: string status: type: string enum: - INCOMPLETE - TRIALING - PENDING_3DS - PENDING_REDIRECT - ACTIVE - PAST_DUE - PAUSED - CANCELED - EXPIRED currentCycle: type: integer totalCycles: type: integer nullable: true trialEndAt: type: string format: date-time nullable: true cancelAtPeriodEnd: type: boolean currentCycleDueAt: type: string format: date-time nullable: true description: >- Period-end / access-expiry clock for BOTH rails (replaces the removed `expiresAt`): card subs renew off-session at this date, crypto subs renew by email around it. Null once no further renewal is scheduled (final cycle reached or terminated). renewalAttempt: type: integer description: >- Attempts made for the current cycle: 0 while healthy, 1..8 while dunning (card smart-retry). nextRenewalAttemptAt: type: string format: date-time nullable: true description: Scheduled next retry while PAST_DUE (card back-off). lastDeclineCategory: type: string nullable: true enum: - SOFT - HARD description: >- Category of the most recent decline: SOFT (retried) or HARD (ends the subscription). externalRef: type: string nullable: true description: Merchant business reference set at create. createdAt: type: string format: date-time updatedAt: type: string format: date-time ScheduledChange: type: object description: A pending upgrade/downgrade recorded by `POST /change-plan`. properties: id: type: string example: ssc_abc123 type: type: string enum: - UPGRADE - DOWNGRADE - INSTRUMENT_CHANGE targetPriceId: type: string nullable: true description: Target plan (recurring Product) id the subscription switches to. example: pro_9m2k1x8s7d6f scheduledFor: type: string format: date-time description: >- When the change applies: `now` for an immediate upgrade, the period end for a downgrade. appliedAt: type: string format: date-time nullable: true description: Null while pending; set once the plan swap has been applied. Payment: type: object description: Public payment shape (`PaymentPublic`). properties: id: type: string example: pay_abc123 organizationId: type: string customerId: type: string nullable: true productId: type: string nullable: true subscriptionId: type: string nullable: true status: $ref: '#/components/schemas/PaymentStatus' declineCode: type: string nullable: true description: >- Normalized decline reason for a FAILED charge (Stripe-parity `decline_code`), e.g. `insufficient_funds`, `not_supported`, `stolen_card`, `expired_card`. Null on non-declined / non-card payments. declineCategory: type: string nullable: true enum: - SOFT - HARD description: >- Retryability of the decline: SOFT = transient (a retry may succeed), HARD = terminal (the credential is unusable). Null when not a decline. displayName: type: string nullable: true displayDescription: type: string nullable: true displayImageUrl: type: string nullable: true priceCents: type: string nullable: true currency: type: string nullable: true tokenAmount: type: string nullable: true tokenFeeAmount: type: string nullable: true quoteFiatAmountCents: type: integer nullable: true quoteFiatCurrency: type: string nullable: true grossAmountCents: type: integer nullable: true platformFeeCents: type: integer nullable: true merchantNetCents: type: integer nullable: true vatAmountCents: type: integer nullable: true vatRateBps: type: integer nullable: true description: >- Applied VAT rate in basis points (2000 = 20%); MoR + EU only, else null taxInclusive: type: boolean description: >- true = price is VAT-inclusive (gross = price); false = exclusive (gross = price + VAT) refundedAmountCents: type: integer nullable: true refundedAt: type: string format: date-time nullable: true cryptoSettlementMode: type: string nullable: true settlementChainId: type: integer nullable: true settlementAsset: type: string nullable: true settlementRecipient: type: string nullable: true depositAddress: type: string nullable: true settlementTxHash: type: string nullable: true successUrl: type: string nullable: true cancelUrl: type: string nullable: true externalRef: type: string nullable: true paymentReceivedAt: type: string format: date-time nullable: true paymentSettledAt: type: string format: date-time nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time expiresAt: type: string format: date-time nullable: true description: >- When an unfinished intent stops being payable. Set for card/APM (bounded to the checkout-session window, else 30 min) and crypto (per-chain deposit window). Past this, an abandoned PENDING intent is swept to EXPIRED. Null only for legacy rows. statusTimeline: type: array description: >- Append-only status history — every status the payment moved through, oldest→newest. The last entry is where it currently stands / stopped. Populated on detail + list reads; empty for legacy rows created before the feature. items: type: object properties: status: type: string description: The status the payment transitioned into. enum: - PENDING - AUTHORIZED - PENDING_3DS - PENDING_REDIRECT - BRIDGING - RECEIVED - PARTIAL - COMPLETED - FAILED - DECLINED - REFUNDED - PARTIALLY_REFUNDED - CANCELED - EXPIRED at: type: string format: date-time description: When the transition happened. asset: type: object nullable: true description: Populated on crypto reads. properties: chainId: type: integer symbol: type: string decimals: type: integer address: type: string description: Token contract / SPL mint, or `NATIVE`. deposit: type: object nullable: true description: Populated on crypto reads while a deposit is being watched. properties: expected: type: string received: type: string remaining: type: string confirmations: type: object nullable: true properties: observed: type: integer required: type: integer detectedAt: type: string format: date-time warnings: type: array items: type: object properties: code: type: string enum: - INSUFFICIENT_DEPOSIT_AMOUNT - RBF_DETECTED - NETWORK_FEE_SURCHARGE message: type: string data: type: object additionalProperties: true Error: type: object required: - success - error properties: success: type: boolean example: false error: type: string description: Machine-readable error code. example: NOT_FOUND message: type: string example: Resource not found data: description: Optional error detail. PaymentStatus: type: string enum: - PENDING - AUTHORIZED - PENDING_3DS - PENDING_REDIRECT - BRIDGING - RECEIVED - PARTIAL - COMPLETED - FAILED - DECLINED - REFUNDED - PARTIALLY_REFUNDED - CANCELED - EXPIRED responses: Unauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: success: false error: UNAUTHORIZED message: Invalid or missing API key securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Suby-Api-Key description: Secret API key. `sk_live_…` (production) or `sk_sandbox_…` (sandbox). ````