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",
  "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",
    "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',
    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',
    '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  \"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  \"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  \"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",
  "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",
    "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',
    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',
    '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  \"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  \"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  \"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"

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"

Retrieve a Subscription

Cancel a subscription

Get Started

API Documentation

Update a subscription

Authorizations

Path Parameters

Body

Response