Skip to main content
POST
/
subscriptions
/
create
/
Create a subscription
curl --request POST \
  --url https://api.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"
}
'
{
  "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"
}

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,
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.

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

​
id
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
​
plan
object
​
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"