Create a subscription

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/create/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "plan-pro-monthly",
  "chargePeriod": "MONTHLY",
  "customerId": "cust_789",
  "successUrl": "https://kelviq.com/subscription/success",
  "features": [
    {
      "identifier": "seats",
      "quantity": 5
    }
  ],
  "ipAddress": "103.154.35.20"
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/subscriptions/create/"

payload = {
    "planIdentifier": "plan-pro-monthly",
    "chargePeriod": "MONTHLY",
    "customerId": "cust_789",
    "successUrl": "https://kelviq.com/subscription/success",
    "features": [
        {
            "identifier": "seats",
            "quantity": 5
        }
    ],
    "ipAddress": "103.154.35.20"
}
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: 'plan-pro-monthly',
    chargePeriod: 'MONTHLY',
    customerId: 'cust_789',
    successUrl: 'https://kelviq.com/subscription/success',
    features: [{identifier: 'seats', quantity: 5}],
    ipAddress: '103.154.35.20'
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/create/', 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/create/",
  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' => 'plan-pro-monthly',
    'chargePeriod' => 'MONTHLY',
    'customerId' => 'cust_789',
    'successUrl' => 'https://kelviq.com/subscription/success',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 5
        ]
    ],
    'ipAddress' => '103.154.35.20'
  ]),
  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/create/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"successUrl\": \"https://kelviq.com/subscription/success\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\"\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/create/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"successUrl\": \"https://kelviq.com/subscription/success\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/subscriptions/create/")

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\": \"plan-pro-monthly\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"successUrl\": \"https://kelviq.com/subscription/success\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\"\n}"

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

{
  "id": "520ca8a5-9fc0-4d6a-bc7a-2ba331595441",
  "startDate": "2026-02-07",
  "endDate": null,
  "billingPeriodStartTime": "2026-02-07T06:02:05Z",
  "billingPeriodEndTime": "2026-02-08T06:02:05Z",
  "amount": "2000.00",
  "recurrence": "month",
  "currency": "USD",
  "status": "trialing",
  "product": {
    "name": "Invoice Test",
    "id": "88e437b8-6017-405b-9328-e0f4e140bb79",
    "identifier": "invoice-test"
  },
  "plan": {
    "name": "iUltra",
    "identifier": "i-ultra"
  },
  "features": [],
  "trialDaysRemaining": 1,
  "customerId": "geojacob",
  "billingType": "SUBSCRIPTION",
  "recurrenceUnit": 1,
  "recurrenceType": "MONTH",
  "files": [
    {
      "id": "bf9f0fe0-c9c0-436d-8811-e412d0365470",
      "name": "custom-pricinig.png",
      "file": "https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png",
      "ordering": 0,
      "enabled": true,
      "downloadUrl": "https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/"
    }
  ],
  "links": [
    {
      "name": "Product documentation",
      "url": "https://example.com/docs"
    }
  ],
  "license": [
    {
      "id": "f81efb90-5f29-4dd1-9c7b-be4085e473de",
      "licenseKey": "10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1",
      "activatedOn": null,
      "expiresOn": null,
      "activationUsage": 0,
      "activationLimit": 2,
      "enabled": true
    }
  ]
}

{
  "detail": "Customer does not exist."
}

POST

subscriptions

create

Create a subscription

curl --request POST \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/create/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "planIdentifier": "plan-pro-monthly",
  "chargePeriod": "MONTHLY",
  "customerId": "cust_789",
  "successUrl": "https://kelviq.com/subscription/success",
  "features": [
    {
      "identifier": "seats",
      "quantity": 5
    }
  ],
  "ipAddress": "103.154.35.20"
}
'

import requests

url = "https://sandboxapi.kelviq.com/api/v1/subscriptions/create/"

payload = {
    "planIdentifier": "plan-pro-monthly",
    "chargePeriod": "MONTHLY",
    "customerId": "cust_789",
    "successUrl": "https://kelviq.com/subscription/success",
    "features": [
        {
            "identifier": "seats",
            "quantity": 5
        }
    ],
    "ipAddress": "103.154.35.20"
}
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: 'plan-pro-monthly',
    chargePeriod: 'MONTHLY',
    customerId: 'cust_789',
    successUrl: 'https://kelviq.com/subscription/success',
    features: [{identifier: 'seats', quantity: 5}],
    ipAddress: '103.154.35.20'
  })
};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/create/', 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/create/",
  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' => 'plan-pro-monthly',
    'chargePeriod' => 'MONTHLY',
    'customerId' => 'cust_789',
    'successUrl' => 'https://kelviq.com/subscription/success',
    'features' => [
        [
                'identifier' => 'seats',
                'quantity' => 5
        ]
    ],
    'ipAddress' => '103.154.35.20'
  ]),
  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/create/"

	payload := strings.NewReader("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"successUrl\": \"https://kelviq.com/subscription/success\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\"\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/create/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planIdentifier\": \"plan-pro-monthly\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"successUrl\": \"https://kelviq.com/subscription/success\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://sandboxapi.kelviq.com/api/v1/subscriptions/create/")

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\": \"plan-pro-monthly\",\n  \"chargePeriod\": \"MONTHLY\",\n  \"customerId\": \"cust_789\",\n  \"successUrl\": \"https://kelviq.com/subscription/success\",\n  \"features\": [\n    {\n      \"identifier\": \"seats\",\n      \"quantity\": 5\n    }\n  ],\n  \"ipAddress\": \"103.154.35.20\"\n}"

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

{
  "id": "520ca8a5-9fc0-4d6a-bc7a-2ba331595441",
  "startDate": "2026-02-07",
  "endDate": null,
  "billingPeriodStartTime": "2026-02-07T06:02:05Z",
  "billingPeriodEndTime": "2026-02-08T06:02:05Z",
  "amount": "2000.00",
  "recurrence": "month",
  "currency": "USD",
  "status": "trialing",
  "product": {
    "name": "Invoice Test",
    "id": "88e437b8-6017-405b-9328-e0f4e140bb79",
    "identifier": "invoice-test"
  },
  "plan": {
    "name": "iUltra",
    "identifier": "i-ultra"
  },
  "features": [],
  "trialDaysRemaining": 1,
  "customerId": "geojacob",
  "billingType": "SUBSCRIPTION",
  "recurrenceUnit": 1,
  "recurrenceType": "MONTH",
  "files": [
    {
      "id": "bf9f0fe0-c9c0-436d-8811-e412d0365470",
      "name": "custom-pricinig.png",
      "file": "https://cdn.kelviq.com/media/organizations/8/plan/1ad723d2-40eb-4bf0-b924-557e6697e788/53c28d460fed421a81f6c6e90114ff4f/custom-pricinig.png",
      "ordering": 0,
      "enabled": true,
      "downloadUrl": "https://api.kelviq.com/api/v1/catalog/plans/10-july/file/bf9f0fe0-c9c0-436d-8811-e412d0365470/download/"
    }
  ],
  "links": [
    {
      "name": "Product documentation",
      "url": "https://example.com/docs"
    }
  ],
  "license": [
    {
      "id": "f81efb90-5f29-4dd1-9c7b-be4085e473de",
      "licenseKey": "10K-080A3A89-8709-4EB5-80BE-BD37B518CCA1",
      "activatedOn": null,
      "expiresOn": null,
      "activationUsage": 0,
      "activationLimit": 2,
      "enabled": true
    }
  ]
}

{
  "detail": "Customer does not exist."
}

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'

Body

application/json

planIdentifier

string

required

The identifier of the specific plan the customer is subscribing to.

Example:

"plan-pro-monthly"

chargePeriod

enum<string>

required

The billing cycle for the subscription. If the plan is free, pass ONE_TIME as the chargePeriod.

Available options:

ONE_TIME,

MONTHLY,

YEARLY,

WEEKLY,

DAILY,

TWENTY_EIGHT_DAYS,

THREE_MONTHS,

SIX_MONTHS

Example:

"MONTHLY"

customerId

string | null

required

The ID of the customer creating the subscription.

Example:

"cust_789"

successUrl

string<url> | null

The URL to which the user will be redirected after a successful subscription creation. Optional.

Example:

"https://kelviq.com/subscription/success"

features

object[] | null

A list of features and their desired quantities.

Show child attributes

Example:

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

ipAddress

string | null

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

Example:

"103.154.35.20"

Response

Subscription Created

string<uuid>

The unique identifier of the created subscription.

Example:

"520ca8a5-9fc0-4d6a-bc7a-2ba331595441"

startDate

string<date>

The start date of the subscription.

Example:

"2026-02-07"

endDate

string<date> | null

The end date of the subscription, if applicable.

Example:

null

billingPeriodStartTime

string<date-time>

The start time of the current billing period.

Example:

"2026-02-07T06:02:05Z"

billingPeriodEndTime

string<date-time>

The end time of the current billing period.

Example:

"2026-02-08T06:02:05Z"

amount

string

The subscription amount.

Example:

"2000.00"

recurrence

string

The recurrence interval of the subscription.

Example:

"month"

currency

string

The currency of the subscription.

Example:

"USD"

status

string

The current status of the subscription.

Example:

"trialing"

product

object

Show child attributes

plan

object

Show child attributes

features

any[]

List of features included in the subscription.

trialDaysRemaining

integer

Number of trial days remaining.

Example:

1

customerId

string

The customer identifier associated with this subscription.

Example:

"geojacob"

files

object[]

Downloadable files attached to the subscription's plan.

Show child attributes

links

object[]

External links attached to the subscription's plan.

Show child attributes

license

object[]

Issued licenses associated with the subscription.

Show child attributes

List Subscriptions

Retrieve a Subscription

Get Started

API Documentation

Create a subscription

Authorizations

Body

Response