List Subscriptions

curl --request GET \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/', 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/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
      "externalSubscriptionId": "sub_1RpoZoSBstCzyocS7iPmith3",
      "startDate": "2025-07-28",
      "endDate": null,
      "billingPeriodStartTime": "2025-07-28T10:46:34Z",
      "billingPeriodEndTime": "2025-08-28T10:46:34Z",
      "amount": "261.00",
      "recurrence": "month",
      "currency": "usd",
      "status": "active",
      "product": "Aphelo",
      "plan": {
        "name": "Premium",
        "identifier": "premium1"
      },
      "features": [
        {
          "id": "b417ae2f-35e2-48f2-a5c4-fdaa99b2b96a",
          "identifier": "products",
          "name": "Products",
          "description": "",
          "featureType": "CUSTOMIZABLE",
          "details": {},
          "isArchived": false,
          "metadata": {},
          "modifiedOn": "2025-06-14T11:36:26.062491Z",
          "meter": {},
          "featureDetails": {
            "units": {
              "plural": "counts",
              "singular": "count"
            }
          },
          "reset": null,
          "resetTime": null,
          "value": 100,
          "hardLimit": false
        }
      ],
      "trialDaysRemaining": 0,
      "customerId": "testuser",
      "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
        }
      ],
      "canceledAt": null,
      "cancellationReason": null,
      "cancellationFeedback": null,
      "cancellationComment": null
    }
  ]
}

Subscriptions

List Subscriptions

Retrieves a paginated list of subscriptions. Optionally filter the results by customer or status.

By default (no status filter), the response contains exactly one row per subscription: its most recent state, excluding records that have expired (end_date in the past) or been superseded by a later update. When status is supplied, that deduplication and exclusion is skipped and matching subscription records are returned directly — so a subscription that has passed through the requested status more than once, or whose only matching record has since expired or been superseded, can appear more than once or in a state you didn’t expect. Use status for point-in-time queries (e.g. “show me everything currently active”); omit it when you want the current, deduplicated view of each subscription.

GET

subscriptions

List Subscriptions

curl --request GET \
  --url https://sandboxapi.kelviq.com/api/v1/subscriptions/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://sandboxapi.kelviq.com/api/v1/subscriptions/', 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/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "09d706ca-58f3-4fb2-818f-5b8623d67e6e",
      "externalSubscriptionId": "sub_1RpoZoSBstCzyocS7iPmith3",
      "startDate": "2025-07-28",
      "endDate": null,
      "billingPeriodStartTime": "2025-07-28T10:46:34Z",
      "billingPeriodEndTime": "2025-08-28T10:46:34Z",
      "amount": "261.00",
      "recurrence": "month",
      "currency": "usd",
      "status": "active",
      "product": "Aphelo",
      "plan": {
        "name": "Premium",
        "identifier": "premium1"
      },
      "features": [
        {
          "id": "b417ae2f-35e2-48f2-a5c4-fdaa99b2b96a",
          "identifier": "products",
          "name": "Products",
          "description": "",
          "featureType": "CUSTOMIZABLE",
          "details": {},
          "isArchived": false,
          "metadata": {},
          "modifiedOn": "2025-06-14T11:36:26.062491Z",
          "meter": {},
          "featureDetails": {
            "units": {
              "plural": "counts",
              "singular": "count"
            }
          },
          "reset": null,
          "resetTime": null,
          "value": 100,
          "hardLimit": false
        }
      ],
      "trialDaysRemaining": 0,
      "customerId": "testuser",
      "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
        }
      ],
      "canceledAt": null,
      "cancellationReason": null,
      "cancellationFeedback": null,
      "cancellationComment": null
    }
  ]
}

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'

Query Parameters

customer_id

string

Optional. The client-defined unique identifier of the customer whose subscriptions will be returned.

status

string

Optional. Filter by subscription status. Accepts a comma-separated list to match any of several statuses, e.g. active,trialing. Common values: incomplete, incomplete_expired, trialing, active, past_due, canceled. See the endpoint description above for how this changes the deduplication behavior of the response.

Example:

"active,trialing"

page_size

integer

Number of results to return per page. Defaults to 10, maximum 100.

Required range: 1 <= x <= 100

page

integer

The initial index from which to return the results.

Response

200 - application/json

A paginated list of subscriptions.

count

integer

string<uri> | null

results

object[]

Show child attributes

Create a charge

Create a subscription

Get Started

API Documentation

List Subscriptions

Authorizations

Query Parameters

Response