Preview a subscription update

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "new_plan_enterprise",
  "chargePeriod": "YEARLY",
  "features": [
    {
      "identifier": "seats",
      "quantity": 10
    }
  ]
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/"

payload = {
    "planIdentifier": "new_plan_enterprise",
    "chargePeriod": "YEARLY",
    "features": [
        {
            "identifier": "seats",
            "quantity": 10
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    planIdentifier: 'new_plan_enterprise',
    chargePeriod: 'YEARLY',
    features: [{identifier: 'seats', quantity: 10}]
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/', 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://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/",
  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([
    'planIdentifier' => 'new_plan_enterprise',
    'chargePeriod' => 'YEARLY',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 10
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ]\n}"

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

{
  "currency": "USD",
  "recurringAmount": 50,
  "recurringAmountUnits": 5000,
  "amountChargedImmediately": 39.5,
  "amountChargedImmediatelyUnits": 3950,
  "nextInvoice": {
    "amountDue": 39.5,
    "amountDueUnits": 3950,
    "nextPaymentAttempt": "2026-09-01T00:00:00Z",
    "lineItems": [
      {
        "description": "Unused time on Pro after 12 Aug 2026",
        "amount": -10.5,
        "amountUnits": -1050
      },
      {
        "description": "Remaining time on Enterprise after 12 Aug 2026",
        "amount": 50,
        "amountUnits": 5000
      }
    ]
  }
}

{
  "detail": "Subscription does not exists"
}

Subscriptions

Preview a subscription update

Calculates the recurring price, next invoice line items and total, and any amount that would be charged immediately for a proposed subscription update. The request uses the same plan, charge-period, and feature fields as Update a subscription. This endpoint does not change the subscription, create an invoice, charge the customer, or write the proposed update to Kelviq.

Amount fields without the Units suffix use the currency’s major unit; fields ending in Units use its minor unit.

POST

subscriptions

{subscriptionId}

update

preview

Preview a subscription update

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "new_plan_enterprise",
  "chargePeriod": "YEARLY",
  "features": [
    {
      "identifier": "seats",
      "quantity": 10
    }
  ]
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/"

payload = {
    "planIdentifier": "new_plan_enterprise",
    "chargePeriod": "YEARLY",
    "features": [
        {
            "identifier": "seats",
            "quantity": 10
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    planIdentifier: 'new_plan_enterprise',
    chargePeriod: 'YEARLY',
    features: [{identifier: 'seats', quantity: 10}]
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/', 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://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/",
  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([
    'planIdentifier' => 'new_plan_enterprise',
    'chargePeriod' => 'YEARLY',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 10
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/preview/")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ]\n}"

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

{
  "currency": "USD",
  "recurringAmount": 50,
  "recurringAmountUnits": 5000,
  "amountChargedImmediately": 39.5,
  "amountChargedImmediatelyUnits": 3950,
  "nextInvoice": {
    "amountDue": 39.5,
    "amountDueUnits": 3950,
    "nextPaymentAttempt": "2026-09-01T00:00:00Z",
    "lineItems": [
      {
        "description": "Unused time on Pro after 12 Aug 2026",
        "amount": -10.5,
        "amountUnits": -1050
      },
      {
        "description": "Remaining time on Enterprise after 12 Aug 2026",
        "amount": 50,
        "amountUnits": 5000
      }
    ]
  }
}

{
  "detail": "Subscription does not exists"
}

Click the base URL in the API playground and select the Sandbox host for test data or the Production host for live data. Use credentials from the same environment.

Authorizations

Authorization

string

header

required

The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer YOUR_API_KEY'

Path Parameters

subscriptionId

string<uuid>

required

The unique identifier of the subscription whose update will be previewed.

Body

application/json

planIdentifier

string

required

The identifier of the proposed new plan.

Example:

"new_plan_enterprise"

chargePeriod

enum<string>

required

The proposed charging period for the subscription.

Available options:

ONE_TIME,

MONTHLY,

YEARLY,

WEEKLY,

DAILY,

TWENTY_EIGHT_DAYS,

THREE_MONTHS,

SIX_MONTHS

Example:

"YEARLY"

prorationBehavior

enum<string> | null

The proposed proration behaviour — amountChargedImmediately in the response reflects it.

Controls when the customer is billed for this change.

IMMEDIATE_CHARGE — prorate and invoice the difference right now.
PRORATE_NEXT_INVOICE — prorate now, but bill it on the next invoice.
NO_PRORATION — the plan changes immediately, but the partial period is neither credited nor charged; the next invoice bills the full new price.

If omitted, the organization's default is used.

Note: changing chargePeriod to a different billing interval (for example MONTHLY to YEARLY) resets the billing cycle and invoices the new period immediately, whichever value you pass. With NO_PRORATION that means the customer is charged for a full new period with no credit for unused time on the old one — call the preview endpoint first to see the exact amount.

Available options:

IMMEDIATE_CHARGE,

PRORATE_NEXT_INVOICE,

NO_PRORATION

Example:

"PRORATE_NEXT_INVOICE"

features

object[] | null

List of proposed features and quantities for the subscription.

Show child attributes

Example:

[{ "identifier": "seats", "quantity": 10 }]

ipAddress

string | null

The IP Address of the customer, for location-based pricing.

Example:

"103.154.35.20"

trialEnd

string | null

The proposed trial end. Accepts "now" or a future ISO 8601 datetime.

Example:

"2027-12-31 23:59:59"

Response

The proposed update was priced successfully; no changes were applied.

currency

string

ISO 4217 currency code for all amounts in the response.

Example:

"USD"

recurringAmount

number

The subscription's new recurring amount in the currency's major unit.

Example:

50

recurringAmountUnits

integer

The subscription's new recurring amount in the currency's minor unit.

Example:

5000

amountChargedImmediately

number

Amount that would be charged immediately in the currency's major unit. This is non-zero only when the update uses immediate invoicing.

Example:

39.5

amountChargedImmediatelyUnits

integer

Amount that would be charged immediately in the currency's minor unit.

Example:

3950

nextInvoice

object | null

Preview of the next provider invoice. null for billing methods that do not provide invoice previews.

Show child attributes

Get Started

API Documentation

Preview a subscription update

Authorizations

Path Parameters

Body

Response