Update a subscription

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "new_plan_enterprise",
  "chargePeriod": "YEARLY",
  "prorationBehavior": "PRORATE_NEXT_INVOICE",
  "features": [
    {
      "identifier": "seats",
      "quantity": 10
    }
  ],
  "ipAddress": "103.154.35.20",
  "trialEnd": "2027-12-31 23:59:59",
  "paymentBehavior": "activate_on_payment"
}
'

import requests

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

payload = {
    "planIdentifier": "new_plan_enterprise",
    "chargePeriod": "YEARLY",
    "prorationBehavior": "PRORATE_NEXT_INVOICE",
    "features": [
        {
            "identifier": "seats",
            "quantity": 10
        }
    ],
    "ipAddress": "103.154.35.20",
    "trialEnd": "2027-12-31 23:59:59",
    "paymentBehavior": "activate_on_payment"
}
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',
    prorationBehavior: 'PRORATE_NEXT_INVOICE',
    features: [{identifier: 'seats', quantity: 10}],
    ipAddress: '103.154.35.20',
    trialEnd: '2027-12-31 23:59:59',
    paymentBehavior: 'activate_on_payment'
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/', 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/",
  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',
    'prorationBehavior' => 'PRORATE_NEXT_INVOICE',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 10
        ]
    ],
    'ipAddress' => '103.154.35.20',
    'trialEnd' => '2027-12-31 23:59:59',
    'paymentBehavior' => 'activate_on_payment'
  ]),
  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/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"prorationBehavior\": \"PRORATE_NEXT_INVOICE\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"trialEnd\": \"2027-12-31 23:59:59\",\n  \"paymentBehavior\": \"activate_on_payment\"\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/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"prorationBehavior\": \"PRORATE_NEXT_INVOICE\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"trialEnd\": \"2027-12-31 23:59:59\",\n  \"paymentBehavior\": \"activate_on_payment\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"prorationBehavior\": \"PRORATE_NEXT_INVOICE\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"trialEnd\": \"2027-12-31 23:59:59\",\n  \"paymentBehavior\": \"activate_on_payment\"\n}"

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

{
  "subscriptionId": "dffaf07e-4517-47db-ba3a-59a05aa2d465"
}

POST

subscriptions

{subscriptionId}

update

Update a subscription

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "new_plan_enterprise",
  "chargePeriod": "YEARLY",
  "prorationBehavior": "PRORATE_NEXT_INVOICE",
  "features": [
    {
      "identifier": "seats",
      "quantity": 10
    }
  ],
  "ipAddress": "103.154.35.20",
  "trialEnd": "2027-12-31 23:59:59",
  "paymentBehavior": "activate_on_payment"
}
'

import requests

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

payload = {
    "planIdentifier": "new_plan_enterprise",
    "chargePeriod": "YEARLY",
    "prorationBehavior": "PRORATE_NEXT_INVOICE",
    "features": [
        {
            "identifier": "seats",
            "quantity": 10
        }
    ],
    "ipAddress": "103.154.35.20",
    "trialEnd": "2027-12-31 23:59:59",
    "paymentBehavior": "activate_on_payment"
}
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',
    prorationBehavior: 'PRORATE_NEXT_INVOICE',
    features: [{identifier: 'seats', quantity: 10}],
    ipAddress: '103.154.35.20',
    trialEnd: '2027-12-31 23:59:59',
    paymentBehavior: 'activate_on_payment'
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/{subscriptionId}/update/', 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/",
  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',
    'prorationBehavior' => 'PRORATE_NEXT_INVOICE',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 10
        ]
    ],
    'ipAddress' => '103.154.35.20',
    'trialEnd' => '2027-12-31 23:59:59',
    'paymentBehavior' => 'activate_on_payment'
  ]),
  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/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"prorationBehavior\": \"PRORATE_NEXT_INVOICE\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"trialEnd\": \"2027-12-31 23:59:59\",\n  \"paymentBehavior\": \"activate_on_payment\"\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/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"new_plan_enterprise\",\n  \"chargePeriod\": \"YEARLY\",\n  \"prorationBehavior\": \"PRORATE_NEXT_INVOICE\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"trialEnd\": \"2027-12-31 23:59:59\",\n  \"paymentBehavior\": \"activate_on_payment\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"prorationBehavior\": \"PRORATE_NEXT_INVOICE\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 10\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\",\n  \"trialEnd\": \"2027-12-31 23:59:59\",\n  \"paymentBehavior\": \"activate_on_payment\"\n}"

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

{
  "subscriptionId": "dffaf07e-4517-47db-ba3a-59a05aa2d465"
}

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 to be updated. Example UUID from docs: 78058918-9746-4280-9b9b-1bd5115eec6e

Body

application/json

planIdentifier

string

required

The identifier of the new plan.

Example:

"new_plan_enterprise"

chargePeriod

enum<string>

required

The new 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

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 features and quantities to update 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

Controls the trial period for the updated subscription. Accepts either the literal string "now" to end any active trial immediately, or an ISO 8601 datetime string (e.g. "2027-12-31 23:59:59") to set a new trial end date. The datetime must be in the future. If omitted, the existing trial behavior is preserved.

Example:

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

paymentBehavior

enum<string> | null

Controls when a paid subscription update takes effect. Set to "activate_on_payment" to keep the current subscription active while payment is pending and apply the new plan, charge period, and features only after payment succeeds. If payment is not completed, the pending update expires and the current subscription remains unchanged. If omitted, the update uses the default immediate behavior.

Available options:

activate_on_payment

Example:

"activate_on_payment"

Response

200 - application/json

UUID of the updated subscription

subscriptionId

string

Example:

"dffaf07e-4517-47db-ba3a-59a05aa2d465"

Get Started

API Documentation

Update a subscription

Authorizations

Path Parameters

Body

Response