Upgrade or downgrade the plan

curl --request POST \
  --url https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_9m2k1x8s7d6f",
  "effective": "auto",
  "proration": "delta",
  "useCustomerPaymentMethod": true,
  "card": {
    "tokenizedInstrument": "<string>"
  },
  "successUrl": "<string>",
  "cancelUrl": "<string>"
}
'

import requests

url = "https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan"

payload = {
    "productId": "pro_9m2k1x8s7d6f",
    "effective": "auto",
    "proration": "delta",
    "useCustomerPaymentMethod": True,
    "card": { "tokenizedInstrument": "<string>" },
    "successUrl": "<string>",
    "cancelUrl": "<string>"
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productId: 'pro_9m2k1x8s7d6f',
    effective: 'auto',
    proration: 'delta',
    useCustomerPaymentMethod: true,
    card: {tokenizedInstrument: '<string>'},
    successUrl: '<string>',
    cancelUrl: '<string>'
  })
};

fetch('https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productId' => 'pro_9m2k1x8s7d6f',
    'effective' => 'auto',
    'proration' => 'delta',
    'useCustomerPaymentMethod' => true,
    'card' => [
        'tokenizedInstrument' => '<string>'
    ],
    'successUrl' => '<string>',
    'cancelUrl' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan"

	payload := strings.NewReader("{\n  \"productId\": \"pro_9m2k1x8s7d6f\",\n  \"effective\": \"auto\",\n  \"proration\": \"delta\",\n  \"useCustomerPaymentMethod\": true,\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_9m2k1x8s7d6f\",\n  \"effective\": \"auto\",\n  \"proration\": \"delta\",\n  \"useCustomerPaymentMethod\": true,\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productId\": \"pro_9m2k1x8s7d6f\",\n  \"effective\": \"auto\",\n  \"proration\": \"delta\",\n  \"useCustomerPaymentMethod\": true,\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "currentCycle": 123,
      "totalCycles": 123,
      "trialEndAt": "2023-11-07T05:31:56Z",
      "cancelAtPeriodEnd": true,
      "currentCycleDueAt": "2023-11-07T05:31:56Z",
      "renewalAttempt": 123,
      "nextRenewalAttemptAt": "2023-11-07T05:31:56Z",
      "externalRef": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "scheduledChange": {
      "id": "ssc_abc123",
      "targetPriceId": "pro_9m2k1x8s7d6f",
      "scheduledFor": "2023-11-07T05:31:56Z",
      "appliedAt": "2023-11-07T05:31:56Z"
    },
    "applied": true,
    "payment": {
      "id": "pay_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "subscriptionId": "<string>",
      "declineCode": "<string>",
      "displayName": "<string>",
      "displayDescription": "<string>",
      "displayImageUrl": "<string>",
      "priceCents": "<string>",
      "currency": "<string>",
      "tokenAmount": "<string>",
      "tokenFeeAmount": "<string>",
      "quoteFiatAmountCents": 123,
      "quoteFiatCurrency": "<string>",
      "grossAmountCents": 123,
      "platformFeeCents": 123,
      "merchantNetCents": 123,
      "vatAmountCents": 123,
      "vatRateBps": 123,
      "taxInclusive": true,
      "refundedAmountCents": 123,
      "refundedAt": "2023-11-07T05:31:56Z",
      "cryptoSettlementMode": "<string>",
      "settlementChainId": 123,
      "settlementAsset": "<string>",
      "settlementRecipient": "<string>",
      "depositAddress": "<string>",
      "settlementTxHash": "<string>",
      "successUrl": "<string>",
      "cancelUrl": "<string>",
      "externalRef": "<string>",
      "paymentReceivedAt": "2023-11-07T05:31:56Z",
      "paymentSettledAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "expiresAt": "2023-11-07T05:31:56Z",
      "statusTimeline": [
        {
          "at": "2023-11-07T05:31:56Z"
        }
      ],
      "asset": {
        "chainId": 123,
        "symbol": "<string>",
        "decimals": 123,
        "address": "<string>"
      },
      "deposit": {
        "expected": "<string>",
        "received": "<string>",
        "remaining": "<string>",
        "confirmations": {
          "observed": 123,
          "required": 123,
          "detectedAt": "2023-11-07T05:31:56Z"
        },
        "warnings": [
          {
            "message": "<string>",
            "data": {}
          }
        ]
      }
    },
    "checkout": {
      "providerPaymentId": "<string>",
      "threeDsChallengeUrl": "<string>",
      "redirectUrl": "<string>",
      "clientSecret": "<string>"
    }
  },
  "message": "<string>"
}

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found",
  "data": "<unknown>"
}

Subscriptions

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).

POST

subscriptions

{id}

change-plan

Upgrade or downgrade the plan

curl --request POST \
  --url https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan \
  --header 'Content-Type: application/json' \
  --header 'X-Suby-Api-Key: <api-key>' \
  --data '
{
  "productId": "pro_9m2k1x8s7d6f",
  "effective": "auto",
  "proration": "delta",
  "useCustomerPaymentMethod": true,
  "card": {
    "tokenizedInstrument": "<string>"
  },
  "successUrl": "<string>",
  "cancelUrl": "<string>"
}
'

import requests

url = "https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan"

payload = {
    "productId": "pro_9m2k1x8s7d6f",
    "effective": "auto",
    "proration": "delta",
    "useCustomerPaymentMethod": True,
    "card": { "tokenizedInstrument": "<string>" },
    "successUrl": "<string>",
    "cancelUrl": "<string>"
}
headers = {
    "X-Suby-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Suby-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    productId: 'pro_9m2k1x8s7d6f',
    effective: 'auto',
    proration: 'delta',
    useCustomerPaymentMethod: true,
    card: {tokenizedInstrument: '<string>'},
    successUrl: '<string>',
    cancelUrl: '<string>'
  })
};

fetch('https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'productId' => 'pro_9m2k1x8s7d6f',
    'effective' => 'auto',
    'proration' => 'delta',
    'useCustomerPaymentMethod' => true,
    'card' => [
        'tokenizedInstrument' => '<string>'
    ],
    'successUrl' => '<string>',
    'cancelUrl' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Suby-Api-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan"

	payload := strings.NewReader("{\n  \"productId\": \"pro_9m2k1x8s7d6f\",\n  \"effective\": \"auto\",\n  \"proration\": \"delta\",\n  \"useCustomerPaymentMethod\": true,\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Suby-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan")
  .header("X-Suby-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"productId\": \"pro_9m2k1x8s7d6f\",\n  \"effective\": \"auto\",\n  \"proration\": \"delta\",\n  \"useCustomerPaymentMethod\": true,\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.beta.suby.fi/v3/subscriptions/{id}/change-plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Suby-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"productId\": \"pro_9m2k1x8s7d6f\",\n  \"effective\": \"auto\",\n  \"proration\": \"delta\",\n  \"useCustomerPaymentMethod\": true,\n  \"card\": {\n    \"tokenizedInstrument\": \"<string>\"\n  },\n  \"successUrl\": \"<string>\",\n  \"cancelUrl\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "subscription": {
      "id": "sub_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "currentCycle": 123,
      "totalCycles": 123,
      "trialEndAt": "2023-11-07T05:31:56Z",
      "cancelAtPeriodEnd": true,
      "currentCycleDueAt": "2023-11-07T05:31:56Z",
      "renewalAttempt": 123,
      "nextRenewalAttemptAt": "2023-11-07T05:31:56Z",
      "externalRef": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    },
    "scheduledChange": {
      "id": "ssc_abc123",
      "targetPriceId": "pro_9m2k1x8s7d6f",
      "scheduledFor": "2023-11-07T05:31:56Z",
      "appliedAt": "2023-11-07T05:31:56Z"
    },
    "applied": true,
    "payment": {
      "id": "pay_abc123",
      "organizationId": "<string>",
      "customerId": "<string>",
      "productId": "<string>",
      "subscriptionId": "<string>",
      "declineCode": "<string>",
      "displayName": "<string>",
      "displayDescription": "<string>",
      "displayImageUrl": "<string>",
      "priceCents": "<string>",
      "currency": "<string>",
      "tokenAmount": "<string>",
      "tokenFeeAmount": "<string>",
      "quoteFiatAmountCents": 123,
      "quoteFiatCurrency": "<string>",
      "grossAmountCents": 123,
      "platformFeeCents": 123,
      "merchantNetCents": 123,
      "vatAmountCents": 123,
      "vatRateBps": 123,
      "taxInclusive": true,
      "refundedAmountCents": 123,
      "refundedAt": "2023-11-07T05:31:56Z",
      "cryptoSettlementMode": "<string>",
      "settlementChainId": 123,
      "settlementAsset": "<string>",
      "settlementRecipient": "<string>",
      "depositAddress": "<string>",
      "settlementTxHash": "<string>",
      "successUrl": "<string>",
      "cancelUrl": "<string>",
      "externalRef": "<string>",
      "paymentReceivedAt": "2023-11-07T05:31:56Z",
      "paymentSettledAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "expiresAt": "2023-11-07T05:31:56Z",
      "statusTimeline": [
        {
          "at": "2023-11-07T05:31:56Z"
        }
      ],
      "asset": {
        "chainId": 123,
        "symbol": "<string>",
        "decimals": 123,
        "address": "<string>"
      },
      "deposit": {
        "expected": "<string>",
        "received": "<string>",
        "remaining": "<string>",
        "confirmations": {
          "observed": 123,
          "required": 123,
          "detectedAt": "2023-11-07T05:31:56Z"
        },
        "warnings": [
          {
            "message": "<string>",
            "data": {}
          }
        ]
      }
    },
    "checkout": {
      "providerPaymentId": "<string>",
      "threeDsChallengeUrl": "<string>",
      "redirectUrl": "<string>",
      "clientSecret": "<string>"
    }
  },
  "message": "<string>"
}

{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found",
  "data": "<unknown>"
}

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Resource not found",
  "data": "<unknown>"
}

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) 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.

Maximum string length: 255

Example:

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

Path Parameters

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

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

enum<string>

Fresh-card upgrade only (when useCustomerPaymentMethod is not set). Ignored for a downgrade / free swap.

Available options:

CARD,

APPLE_PAY,

GOOGLE_PAY

card

object

Show child attributes

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.

Show child attributes

message

string

Cancel a subscription Retrieve a subscription

Overview

Endpoints

Upgrade or downgrade the plan

Authorizations

Headers

Path Parameters

Body

Response