Skip to main content
POST
/
catalog
/
plans
Create a plan
curl --request POST \
  --url https://api.kelviq.com/api/v1/catalog/plans/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Pro Monthly",
  "identifier": "pro-monthly",
  "description": "Pro tier billed monthly.",
  "product": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
  "isVisible": true,
  "fileKeys": [
    "tmp/9b1c8af2-3d4e-4f9a-8b2c-1f3e5a7b9d12/plan-terms.pdf"
  ],
  "ordering": 1
}
'
{
  "identifier": "pro-monthly",
  "name": "Pro Monthly",
  "description": "Pro tier billed monthly.",
  "product": "0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de",
  "metadata": {},
  "version": 3,
  "isLatest": true,
  "modifiedOn": "2025-04-12T08:21:14.910Z",
  "createdOn": "2025-03-01T08:21:14.910Z",
  "details": {
    "stripeProductId": "prod_ABC123"
  },
  "isVisible": true,
  "isImported": false,
  "countries": [
    "US",
    "IN"
  ],
  "license": {
    "enabled": true,
    "activationLimit": 3,
    "activationLimitEnabled": true,
    "durationUnit": "YEAR",
    "durationValue": 1,
    "hasExpiry": true
  },
  "links": [
    {
      "name": "Product page",
      "url": "https://example.com/product"
    }
  ],
  "files": [
    {
      "id": "7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0",
      "name": "Plan Terms.pdf",
      "file": "media/.../plans/<id>/<uuid>/terms.pdf",
      "ordering": 0,
      "enabled": true,
      "downloadUrl": "https://api.kelviq.com/api/v1/catalog/plans/pro-monthly/file/7a3e3411-cef0-4f4e-bdb6-1f74a4f4d2c0/download/"
    }
  ],
  "ordering": 1
}

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
​
name
string
required
Example:

"Pro Monthly"

​
product
string<uuid>
required

UUID of the parent product.

Example:

"0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de"

​
identifier
string
Example:

"pro-monthly"

​
description
string
Example:

"Pro tier billed monthly."

​
metadata
object
Example:
{}
​
isVisible
boolean
Example:

true

​
license
object

License configuration for a plan (used when issuing license keys).

​
links
object[]
​
fileKeys
string[]

Temporary S3 keys (e.g. tmp/<uuid>/<filename>) returned by POST /media/ for files to attach to the plan. Uploaded files are moved into permanent storage and exposed via the plan's files[].

Example:
[
  "tmp/9b1c8af2-3d4e-4f9a-8b2c-1f3e5a7b9d12/plan-terms.pdf"
]
​
ordering
integer
Example:

1

Response

Plan created.

A versioned plan attached to a product. Updates create new versions; only the published version is is_latest=true.

​
identifier
string

URL-safe slug. Stable across versions.

Example:

"pro-monthly"

​
name
string
Example:

"Pro Monthly"

​
description
string
Example:

"Pro tier billed monthly."

​
product
string<uuid>

UUID of the parent product.

Example:

"0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de"

​
metadata
object
Example:
{}
​
version
integer
read-only
Example:

3

​
isLatest
boolean
read-only

True only for the currently published version.

Example:

true

​
modifiedOn
string<date-time>
read-only
Example:

"2025-04-12T08:21:14.910Z"

​
createdOn
string<date-time>
read-only
Example:

"2025-03-01T08:21:14.910Z"

​
details
object
read-only

Provider-side identifiers (e.g. stripeProductId).

Example:
{ "stripeProductId": "prod_ABC123" }
​
isVisible
boolean
Example:

true

​
isImported
boolean
read-only
Example:

false

​
countries
string[]
read-only
Example:
["US", "IN"]
​
license
object

License configuration for a plan (used when issuing license keys).

​
links
object[]
​
files
object[]
read-only
​
ordering
integer | null
Example:

1